Resultados de aprendizagem

1. Elaborar relatórios técnicos em IT.
2. Estruturar documentação clara para diferentes audiências.
3. Usar ferramentas colaborativas (Markdown, Git, wikis).

Tipos de documento técnico

Adequar ao leitor

Para cada tipo:

1. Quem vai ler? Director, técnico, utilizador comum?
2. O que já sabe? Vocabulário técnico permitido ou não?
3. Que decisões vai tomar com isto? Aprovar verba? Resolver incidente?
4. Quanto tempo tem? Resumo executivo vs documento longo.

Secções clássicas

1. Sumário executivo (1/2 página) — o quê, porquê, conclusão.
2. Introdução — contexto, objectivo, âmbito.
3. Procedimento — o que foi feito, em ordem.
4. Resultados — dados, métricas, capturas.
5. Conclusões — interpretação.
6. Recomendações — próximos passos.
7. Anexos — logs, prints, configurações.

Princípios

• Clareza — frases curtas, voz activa.
• Concisão — sem redundância, sem palavras vazias.
• Estrutura visual — títulos, listas, tabelas.
• Capturas e diagramas quando ajudam.
• Datas, versões, autores sempre.
• Numeração de versão (v1.0, v1.1).

Markdown · porquê

• Plain text — funciona em qualquer editor, sobrevive décadas.
• Versionável em Git — diffs claros, history rica.
• Converte para HTML, PDF, DOCX (via Pandoc).
• Sintaxe simples: #, **, -, [link](url).

# Relatório de intervenção · servidor DB-01

**Data:** 19/05/2026
**Técnico:** João Silva

## Sumário
Substituição de disco em falha S.M.A.R.T.
Downtime: 35 min.

## Procedimento
1. Backup confirmado às 22:00.
2. Servidor desligado às 22:30.
...

Ferramentas

Post-mortem

Documento sem culpa que analisa um incidente após resolução.

Estrutura típica:

• Timeline com horas exactas.
• Impacto — utilizadores afectados, tempo de downtime.
• Causa raiz — análise técnica.
• O que correu bem.
• O que correu mal.
• Acções correctivas com responsáveis e prazos.

Runbook

Procedimento operacional executável sob pressão.

• Passos numerados, claros, copy-paste pronto.
• Comandos exactos, não "executar comando que actualiza X".
• Verificações entre passos ("Se ver erro Y, ir para passo 7").
• Critérios de rollback.

## Restart de aplicação web

1. `ssh user@app-01`
2. `sudo systemctl status aulify-web` (deve estar "active")
3. Se parado: `sudo systemctl start aulify-web`
4. Verificar saúde: `curl localhost:3000/health`
   - Esperado: `{"status":"ok"}`

Documentação morre — como evitar

• Single source of truth — uma localização canónica por tópico.
• Próxima do código — README na pasta do código, não em Google Drive obscuro.
• Revisões periódicas (3 ou 6 meses).
• Owner explícito em cada documento.
• Issues / PRs para mudanças.