Diátaxis: um framework para melhores documentações técnicas · lemuelroberto

Introdução

Como é bom encontrar uma documentação decente quando nos deparamos com um problema ou temos uma dúvida. 🤓

Por outro lado, como é difícil e trabalhoso escrever e manter uma boa documentação técnica. 😭

É com o objetivo de melhorar e organizar nossas documentações, que o framework Diátaxis foi concebido.

Detalhes

O Diátaxis é um framework para organizar a documentação técnica que ajuda as pessoas e times a criarem conteúdos claros e eficazes, focando em quatro propósitos específicos que os usuários possam ter.

Ele divide a documentação em quatro categorias:

Tutoriais: Guiam iniciantes passo a passo através de um processo para ajudá-los a aprender algo novo do zero. Pense neles como uma receita de culinária que ensina você a preparar um prato.

Guias de Como Fazer: São instruções práticas para completar uma tarefa específica ou resolver um problema. Se tutoriais são como aulas de culinária, guias de como fazer são como um manual sobre "Como Assar um Bolo" com todos os passos detalhados.

Referência: Estas são informações factuais e diretas sobre um tópico. Documentação de referência é como um dicionário ou um livro didático que fornece definições, listas de funções e detalhes precisos.

Explicações: Fornecem o "porquê" de algo, explicando conceitos, ideias ou como as coisas funcionam. Pense em explicações como artigos que discutem por que certos ingredientes são usados em uma receita ou como diferentes técnicas afetam o resultado.

Conclusão

Ao estruturar a documentação dessa maneira, o Diátaxis facilita para os usuários encontrarem a informação que precisam com base em seu objetivo atual - seja aprendendo, fazendo, verificando fatos ou entendendo conceitos.

Como é a documentação técnica dos projetos que você trabalha?

Tem alguma boa referência para compartilhar? Coloca aqui nos comentários 🤓

Referências

@hbm, os dois são na verdade muito diferentes e podem ser utilizados em conjunto.

O Diátaxis é um framework no sentido mais amplo da palavra e não uma ferramenta. o MKdocs, sim, é uma ferramenta para a gestão de documentação.

Para referência, tirei 2 definições mais amplas de framework da Wikipedia.

Definição técnica:

Um framework ou arcabouço conceitual, é um conjunto de conceitos usado para resolver um problema de um domínio específico. Framework conceitual não se trata de um software executável, mas sim de um modelo de dados para um domínio.

Definição de administração:

Em administração, um framework é uma estrutura conceitual básica que permite o manuseio homogêneo de diferentes objetos de negócio. Serve para incrementar a disciplina de gestão e predefinir entregáveis comuns para cada objeto de negócio.