Padrões de documentação

Combinados de como o time cria, formata e mantém docs, pra que toda documentação tenha a mesma cara e dure.

Hard

O que é

Padrões de documentação são as regras que dão consistência ao que o time escreve, abrangendo estrutura, estilo, formatação, versionamento e manutenção. Em vez de cada pessoa documentar do seu jeito, todo mundo segue um mesmo molde, e assim quem lê sempre encontra a informação no lugar esperado.

Em produto, isso costuma virar um formato fixo pra requisito, pra registro de decisão, com o porquê e os trade-offs, e pra processo. O ganho é evitar mal-entendido, scope creep e aquele debate repetido sobre uma questão que já tinha sido resolvida. De quebra, esse padrão protege o conhecimento no momento em que alguém deixa o time.

Em uma frase

Já que vamos crescer o time, melhor definir um padrão de documentação antes que cada um escreva do seu jeito.

A pergunta que ele responde

Como faço pra toda doc do time ter a mesma cara e ser fácil de achar?

Quando usar

Ajuda quando o time cresce e a documentação começa a virar bagunça, com cada um num formato e ninguém achando nada.

Como não usar

O cuidado é criar um padrão tão pesado que ninguém segue. Regra demais acaba travando a escrita, que era exatamente o oposto do que o padrão deveria fazer.

Na prática

Pense em todas as specs seguindo o mesmo template, com problema, escopo e critério de sucesso sempre na mesma ordem. Quem lê sabe onde achar cada coisa em segundos, porque já conhece o formato.

Não confunda com

Vale separar os padrões de documentação da documentação em si. O padrão é a regra de como escrever, enquanto a doc é o conteúdo já escrito. Um é a forma combinada, o outro é o que você produz seguindo essa forma.

Operação

Em inglês

Documentation Standards

Pronúncia

n/a

Também chamado de

padrão de doc, guia de documentação, template de doc

Origem

n/a

Fonte

Saiba mais

Write the Docs, guia comunitário sobre padrões de documentação