Elaborar relatórios técnicos

Apresentação

UC02823 (25h · 2,25 pts) cobre a produção de documentação técnica em contexto de IT: relatórios de intervenção, manuais, runbooks, post-mortems. Aprende-se a estruturar texto para diferentes audiências e a usar Markdown + Git como ferramenta principal.

Porque é importante

Um técnico que não documenta cria dependência da sua presença. Quem documenta: - Permite que outros resolvam o problema sem o chamar. - Acelera onboarding de novos colegas. - Protege-se em auditorias (RGPD, ISO 27001). - Reduz tempo de recuperação em incidentes.

"Se não está escrito, não aconteceu" — máxima de auditoria.

Tipos de documento técnico

Relatório de intervenção

Documento que regista uma intervenção pontual num sistema. Tipicamente curto (1-3 páginas).

Quando usar: após reparação de avaria, instalação de novo equipamento, alteração de configuração crítica.

Estrutura: 1. Cabeçalho — data, hora, técnico, cliente/sistema. 2. Problema reportado. 3. Diagnóstico feito. 4. Acções executadas (lista numerada). 5. Resultado e validação. 6. Recomendações. 7. Anexos — fotos, logs, capturas.

Manual de utilizador

Para o utilizador final do sistema. Linguagem simples, sem jargão técnico, com muitas capturas.

Estrutura típica: - Introdução — o que faz o sistema. - Primeiros passos — login, interface principal. - Tarefas comuns — passo-a-passo de cada uso. - FAQ. - Contactos de suporte.

Manual de administração

Para IT/sysadmin. Pode usar vocabulário técnico, mas continua a precisar de clareza.

Cobre instalação, configuração, manutenção, troubleshooting, upgrade.

Documentação de API

Para programadores que vão consumir a API. Standards:

• OpenAPI / Swagger — descreve REST APIs em YAML/JSON.
• API Blueprint — alternativa.
• GraphQL — schema auto-documenta.

Inclui endpoints, parâmetros, exemplos de request/response, códigos de erro, autenticação.

Runbook

Procedimento operacional executável em situação de stress.

Características: - Passos numerados, sem ambiguidade. - Comandos exactos copy-paste, não descrições. - Verificações de estado entre passos. - Critérios claros de sucesso/falha. - Rollback definido.

Post-mortem

Análise feita após um incidente, sem atribuição de culpa pessoal.

Estrutura: - Resumo (incidente, duração, impacto). - Timeline com horas exactas. - Causa raiz (análise técnica profunda). - O que correu bem. - O que correu mal. - Acções correctivas com responsável e prazo.

Cultura blameless — focar no sistema, não na pessoa. Erros humanos são sintomas de processos fragéis.

Adequar à audiência

Antes de escrever, perguntar:

1. Quem lê? Director, técnico junior, utilizador comum, auditor.
2. O que já sabe? Pode usar termos como "VLAN", "DHCP", "API"?
3. Que decisão vai tomar? Aprovar verba, executar acção, validar conformidade.
4. Quanto tempo tem? Sumário executivo de 1 parágrafo vs documento detalhado.

Exemplo: incidente de rede caída na escola

Mesmo problema, 3 documentos diferentes:

Princípios de escrita técnica

Clareza

• Frases curtas (média 15-20 palavras).
• Voz activa — "O técnico instalou o disco" e não "O disco foi instalado pelo técnico".
• Vocabulário consistente — se chamas "servidor", não passes a chamar "máquina" sem aviso.

Concisão

• Cortar palavras vazias ("é importante referir que...").
• 1 ideia por parágrafo.
• Se podes dizer em menos, di-lo em menos.

Estrutura visual

• Títulos hierárquicos (#, ##, ###).
• Listas quando há enumeração.
• Tabelas quando há comparação.
• Negrito em palavras-chave (com moderação).
• Espaço em branco — texto compacto cansa.

Capturas e diagramas

• Captura quando palavras não chegam ("clica no botão azul no canto").
• Diagramas para arquitectura, fluxos, redes.
• Etiquetar capturas com setas/números se referenciadas no texto.

Markdown

Sintaxe essencial

# Título 1
## Título 2
### Título 3

**negrito**  _itálico_  `código inline`

- Lista
- Não-ordenada

1. Lista
2. Ordenada

[link](https://example.com)

![imagem](caminho.png)

> Citação

| Coluna A | Coluna B |
|---|---|
| Valor | Valor |

```bash
codigo em bloco

### Vantagens

- **Texto puro** — abre em qualquer editor.
- **Versionável** em Git — diffs claros.
- **Converte** para HTML, PDF, DOCX via Pandoc.
- **Sintaxe minimal** — aprende-se em 30 minutos.

### Conversão

```bash
# MD → PDF
pandoc relatorio.md -o relatorio.pdf

# MD → DOCX
pandoc relatorio.md -o relatorio.docx

# MD → HTML
pandoc relatorio.md -o relatorio.html

Documentação versionada com Git

Estrutura típica em repositório

projecto/
├── README.md           # entrada principal
├── docs/
│   ├── arquitetura.md
│   ├── instalacao.md
│   ├── api/
│   │   └── openapi.yaml
│   └── runbooks/
│       ├── restart-app.md
│       └── restore-db.md
└── CHANGELOG.md        # histórico de versões

README · boas práticas

Primeiro contacto. Deve responder em 30 segundos:

1. O que é este projecto?
2. Como instalar/correr localmente?
3. Onde estão docs avançadas?
4. Como contribuir?
5. Licença?

Ferramentas

Wikis colaborativas

• Notion — moderno, blocos flexíveis, fraco em export.
• Confluence — empresarial, integra Jira.
• GitBook — bom para docs públicas.
• MediaWiki — Wikipedia engine, robusto.

Sites de documentação

• MkDocs — Python, simples, Material theme excelente.
• Docusaurus — React, da Meta, popular em projectos open-source.
• Hugo — Go, super rápido, flexível.
• VitePress — Vue, simples, moderno.

Diagramas

• Mermaid — texto → diagrama, integrado em GitHub/GitLab.
• draw.io / diagrams.net — interface visual gratuita.
• PlantUML — texto → UML.
• Excalidraw — esquemas "à mão" elegantes.

Capturas

• Flameshot (Linux), ShareX (Windows), CleanShot (macOS) — anotam directamente.
• OBS ou Loom — vídeos curtos quando texto não chega.

Manter documentação viva

Causas comuns de "doc rot"

1. Mudança de código sem actualizar doc.
2. Múltiplas localizações divergentes.
3. Sem owner responsável.
4. Sem revisões periódicas.

Práticas anti-rot

• Single source of truth — uma localização canónica por tópico.
• Próxima do código — README no repo, não em pasta de partilha esquecida.
• Owner explícito em cabeçalho ou metadata.
• Última revisão documentada.
• Issues quando alguém detecta info errada.
• PRs para mudanças em docs críticas.
• Revisão trimestral agendada.

Caso prático · relatório de instalação

Exemplo curto

# Relatório de instalação · Servidor de impressão

**Data:** 19 de Maio de 2026
**Técnico:** João Pereira
**Local:** Escola Sec. Vagueira, Sala 12 (rack principal)
**Equipamento:** HP Color LaserJet Pro M454dw

## Sumário

Instalado novo servidor de impressão para a sala dos professores. 25
postos com acesso configurado. Sem incidentes; intervenção concluída
em 1h45.

## Procedimento

1. Configurada impressora com IP estático `192.168.20.50`.
2. Instalado servidor de impressão CUPS em VM Linux existente
   (`print-srv-01.escola.local`).
3. Driver universal HP descarregado e adicionado.
4. Fila partilhada com nome `Impressora-Sala-Profs`.
5. Em cada um dos 25 PCs, adicionada impressora via:
   - Windows: `\\print-srv-01\Impressora-Sala-Profs`.
   - Tempo médio por PC: 2 min.
6. Testes de impressão em cor e P&B em 3 PCs aleatórios. OK.

## Recomendações

- Renovar toner antes de Setembro (consumo expectável > 80%).
- Adicionar à monitorização (já tem agente SNMP).

Apêndices

A · Checklist para relatório

• [ ] Cabeçalho com data, autor, sistema.
• [ ] Sumário em 3 linhas.
• [ ] Procedimento numerado e reproduzível.
• [ ] Comandos exactos quando aplicável.
• [ ] Resultados com prova (captura, log, output).
• [ ] Recomendações futuras.
• [ ] Revisão por outro técnico antes de entregar.

B · Glossário

API. Application Programming Interface. Markdown. Linguagem de marcação leve. Post-mortem. Análise após incidente. Runbook. Procedimento operacional. SLA. Service Level Agreement.

C · Recursos

• Pandoc · pandoc.org — converte tudo em tudo.
• MkDocs Material · squidfunk.github.io/mkdocs-material/
• Google Developer Style Guide · developers.google.com/style
• Microsoft Writing Style Guide.