Quem estará lendo a documentação? Para que a documentação será usada? Essas são as perguntas mais importantes a serem respondidas. Por exemplo, a documentação para desenvolvedores de manutenção se concentraria mais na estrutura, enquanto a documentação para desenvolvedores que se integram ao produto se concentraria mais em serviços da Web e estrutura de banco de dados.
Em geral, faça a documentação necessária e não mais. Muitas organizações exigem documentação porque alguém insistiu que é uma prática recomendada, mas a documentação acaba acumulando poeira.
Supondo que as pessoas realmente usem a documentação, não tente capturar o código e o banco de dados no nível mais baixo. Os desenvolvedores analisarão o código em busca de minúcias. Em vez disso, concentre-se nos detalhes que não são aparentes no código , por exemplo:
- Os casos de uso que o produto atende. Isso pode ser difícil, considerando a idade do produto, mas capturar o que o produto deve fazer fornece um contexto vital para leitores e testadores não técnicos. Quem são os concorrentes no mercado (se houver)? Há algo excluído do escopo do produto?
- Quaisquer requisitos não funcionais claros . Por exemplo, o produto foi escrito para lidar com um determinado volume? Qual a idade dos dados? Onde o cache é usado? Como os usuários são autenticados? Como o controle de acesso funciona?
- Um diagrama de contexto mostrando a interação com outros sistemas, como banco de dados, fontes de autenticação, backup, monitoramento e assim por diante.
- (Se conhecido) Riscos e como eles foram mitigados junto com um registro de decisão . Provavelmente, isso é difícil em retrospecto, mas muitas vezes existem decisões críticas que influenciam um design. Capture tudo o que você conhece.
- Padrões de design comuns ou diretrizes de design . Por exemplo, existe uma maneira padrão de acessar o banco de dados? Existe um padrão de codificação ou nomeação?
- Caminhos de código críticos , geralmente usando fluxogramas ou atividade UML ou diagramas de sequência. Pode não haver nenhum no projeto, mas esses geralmente são aqueles que os usuários de negócios articularam.
Mesmo se todas essas informações não estiverem disponíveis, comece agora . Os desenvolvedores que vierem depois de você agradecerão.
Bons testes de unidade automatizados ou casos de teste também podem ser uma documentação útil, embora difícil de acessar para pessoas menos técnicas.
Também parece que você precisa fazer uma mudança cultural para incluir a documentação . Comece pequeno, mas, idealmente, o projeto não deve ser "concluído" até que tenha pelo menos um nível mínimo de documentação. Este é provavelmente o passo mais difícil, porque o que precede são coisas que você pode controlar. Isso é algo que os outros devem comprar. No entanto, também pode ser o mais gratificante, principalmente se o próximo projeto que você fizer vier com boa documentação.