Mini-Projecto · Dossier de documentação de um sistema

Documentar um sistema real do princípio ao fim

⏱ Duração estimada: 6 horas (≈ 3-4 aulas) ↗ Referencial SNQ

Índice

Contexto
Requisitos
Fases
Critérios de avaliação
Reflexão

Contexto

Cada par/trio escolhe um sistema real que conheça (Moodle da escola, app que usa diariamente, software que instalou no PC, servidor de jogos, etc.) e produz uma dossier de documentação completa: 4 tipos de documento que cobrem audiências diferentes.

Requisitos

Funcionais

README do sistema (overview para alguém que nunca o viu).
Manual de utilizador (15+ passos com capturas).
Runbook operacional (procedimento sob pressão).
Relatório de instalação (como foi posto a funcionar).
Diagrama de arquitectura (Mermaid, draw.io ou outro).

Não-funcionais

Tudo em Markdown, num repositório Git público (GitHub/GitLab).
README como entrada única; outros documentos linkados.
Pelo menos 3 commits diferentes (mostrando histórico).
Capturas anotadas com setas/números quando necessário.

Fases

Fase 1 · 1h

Escolha e levantamento

Escolher sistema (validar com professor).
Listar tipos de utilizador (utilizador comum, admin, externo).
Esboço do dossier: que documentos, ordem, ligações entre eles.

Documento de 1 página com plano + repositório Git criado.

Fase 2 · 1h

README e arquitectura

README com: descrição, audiência, requisitos, instalação rápida, links.
Diagrama de arquitectura (Mermaid recomendado por ser texto).

README.md + arquitectura.md com diagrama.

Fase 3 · 1.5h

Manual de utilizador

Para utilizador final.
Mínimo 15 passos com capturas.
Linguagem simples, sem jargão.
FAQ no fim.

manual-utilizador.md + pasta imagens/.

Fase 4 · 1h

Runbook

Procedimento operacional executável.
Mínimo 8 passos numerados com comandos exactos.
Pré-verificações, verificação final, rollback.

runbook.md na pasta runbooks/.

Fase 5 · 1h

Relatório + apresentação

Relatório de instalação (1-2 páginas) descrevendo como puseram o sistema a funcionar.
Compilar dossier final.
Apresentar 5 min ao resto da turma.

relatorio-instalacao.md + slides curtos + dossier completo no Git.

Critérios de avaliação

Item	Peso
Estrutura clara do dossier	15%
README útil e bem escrito	15%
Manual de utilizador (clareza + capturas)	20%
Runbook executável e completo	20%
Relatório de instalação	10%
Diagrama de arquitectura	10%
Uso correcto de Git (commits, history)	5%
Apresentação	5%

Reflexão

Em meia página: documentar é fácil ou difícil para ti? Que documento custou mais? Como ensinarias um colega a documentar melhor?