ORG-0004 — Sistema de documentação

Sem lugar certo para cada tipo de documento, o mesmo assunto aparece em três lugares, um deles desatualizado, e o documento de visão incha com detalhe de implementação.

1. Toda stack tem os mesmos documentos, no mesmo lugar:
   • README.md: a porta de entrada (o que é, estado, como rodar, pré-requisitos);
   • docs/ARCHITECTURE.md: a visão técnica viva, de alto nível, com um parágrafo e um link por capability e nenhum parágrafo datado;
   • docs/stack.md: a ficha da stack (tecnologia e versões);
   • docs/produto/: para quem e para quê, e o glossário;
   • docs/decisoes/: ADRs e, em organizacao/, a cópia das ORGs;
   • docs/solucoes/: como algo foi montado em detalhe;
   • docs/guias/: passo a passo operacional;
   • docs/acesso/: permissões e perfis de cada aplicação;
   • docs/design-system/: famílias de cor, estados e pedidos.
2. Toda change atualiza a documentação que toca na mesma change.
3. O presente é o que está escrito; o passado está no Git e nas changes arquivadas.

• Quem chega sabe onde procurar cada coisa, em qualquer stack.
• A revisão de change confere a documentação junto com o código.

O detalhe está na documentação da arquitetura.