O que é documentação
Documentação é o registro que explica como usar e manter um sistema. Ela reúne o guia do usuário, a referência da API e as notas de operação que orientam o trabalho.
O valor aparece na consulta. A documentação economiza a investigação que alguém repetiria para descobrir o que o sistema faz e como alterá-lo.
Guia e referência
O guia conduz por um percurso, e a referência descreve cada parte. O público novo segue o guia, e quem mantém o projeto consulta a seção específica que precisa.
Manter junto da mudança
A documentação precisa acompanhar a alteração que ela descreve. Uma mudança aceita no sistema que não chega ao documento cria duas referências incompatíveis para a próxima tarefa.
O Markdown e a escrita técnica ajudam a manter o texto simples e versionado. A diferença entre versões fica clara no histórico, e a revisão da mudança confere o documento junto do código.
O mínimo que funciona
A documentação serve quando responde ao uso. Confira se a pergunta que motivou a leitura foi respondida antes de acrescentar seção nova, e remova o trecho que deixou de valer.
Para revisar a documentação de um projeto construído com agentes, o Desenvolvimento Colaborativo da Dev Side Studio permite conferir o registro e a implementação durante a sessão.
Dúvidas frequentes
Perguntas frequentes sobre Documentação
- Documentação precisa cobrir tudo?
- Não. Ela precisa responder às perguntas que aparecem no uso. Documentar demais o que ninguém consulta custa manutenção sem ajudar quem precisa da resposta.
- Qual a diferença entre guia e referência?
- O guia conduz o leitor por um percurso, e a referência descreve cada parte com precisão. O usuário novo começa pelo guia, e quem já conhece consulta a referência por função.
- Quando a documentação precisa ser atualizada?
- No momento da mudança. Uma alteração aceita no sistema que não chega à documentação cria duas fontes incompatíveis, e a próxima consulta parte de uma informação antiga.
Para continuar
Recursos relacionados
Site de referência
Wikipedia: documentação técnica
Apresenta o registro de uso e manutenção de um sistema e os tipos de documento.
Abrir recursoSite de referência
Diátaxis: framework de documentação
Organiza a documentação em tutorial, guia prático, explicação e referência.
Abrir recursoAplicação na formação
Developer Workspace
A documentação registra o comportamento e o uso do sistema para quem mantém o projeto.
Conhecer a formação
Fontes consultadas
Referências deste verbete
Este verbete ajudou você?
Obrigado pela resposta. Ela fica salva apenas neste navegador.