O que é o Diataxis

Se você já abriu a documentação de uma biblioteca e ficou perdido sem saber se devia ler o tutorial, o guia rápido ou a referência da API, você viveu o problema que o Diataxis resolve.

Diataxis e um framework de organização de documentação técnica criado por Daniele Procida e publicado em diataxis.fr. O nome vem do grego e significa "disposição em ordem". A ideia central e simples: toda documentação serve a um dos 4 propósitos diferentes, e mistura-los num mesmo lugar confunde o leitor.

O projeto ganhou popularidade significativa na comunidade de devs ao ser adotado por projetos grandes como Django, NumPy e Ubuntu. Em 2026, o site entrou no topo do Hacker News com mais de 160 pontos, mostrando que o problema de docs ruins continua muito presente.

Como funciona o framework

O Diataxis divide toda documentação em 4 quadrantes, baseados em dois eixos: o leitor esta aprendendo ou trabalhando? E o conteúdo e prático ou teórico?

  • Tutorial: ensina fazendo. O leitor aprende enquanto executa um exemplo guiado. Foco total em completar a tarefa, não em explicar cada detalhe.
  • Guia prático (How-to guide): assume que o leitor já sabe o básico e quer resolver um problema específico. Ex: "Como configurar autenticação JWT".
  • Referência (Reference): informação técnica precisa e completa. O leitor consulta quando precisa saber o que um parâmetro aceita ou qual e a assinatura de uma função.
  • Explicação (Explanation): aprofunda o entendimento. Contextualiza decisões de design, histórico e alternativas. Não ensina a fazer, ensina a entender.

Cada tipo tem um objetivo diferente, e escrita-los juntos gera confusão. Um tutorial que para para explicar teoria perde o ritmo. Uma referência que tenta ensinar iniciantes falha em ser precisa.

💡
Dica

Se um paragrafo da sua doc serve a dois propósitos ao mesmo tempo, provavelmente precisa ser dividido em dois documentos separados.

Principais recursos e diferenciais

O Diataxis não e uma ferramenta de software, e um sistema conceitual. Você pode aplica-lo em qualquer plataforma: Docusaurus, MkDocs, Notion, Confluence, GitHub Wiki ou até em pastas simples de Markdown.

  • Framework agnosto de tecnologia: funciona independente de como você escreve ou pública a doc.
  • Orientado ao leitor: a divisão não e sobre o que você quer escrever, e sobre o que o leitor precisa no momento.
  • Diagnóstico de problemas: ao revisar docs existentes pelo filtro do Diataxis, você rapidamente identifica conteúdo misturado, secoes que não deveriam existir e lacunas reais.
  • Gratuito e open source: o site e a explicação completa estão em diataxis.fr sem custo algum.
  • Adotado por grandes projetos: Django, NumPy, Divio e Ubuntu usam ou inspiraram o framework, o que prova que ele escala para projetos grandes.

O diferencial principal em relação a outras abordagens (como o modelo tradicional de "página por tópico") e que o Diataxis força uma conversa sobre por que aquele conteúdo existe, não apenas o que ele diz.

Como começar: aplicando o Diataxis no seu projeto

Você não precisa reescrever toda a sua documentação de uma vez. O processo recomendado e incremental.

Passo 1: Leia o site oficial (diataxis.fr) e entenda os 4 quadrantes. Menos de 30 minutos para absorver o conceito principal.

Passo 2: Audite o que você já tem. Liste cada página da sua doc atual e classifique em qual quadrante ela se encaixa. Páginas que não se encaixam em nenhum são candidatas a exclusão ou fusão.

Passo 3: Crie uma estrutura de pastas ou secoes que reflita os 4 tipos:

docs/
  tutoriais/          # Aprendizado guiado
    primeiros-passos.md
  guias/              # Como resolver X
    como-configurar-autenticação.md
  referência/         # API, parâmetros, tipos
    api-endpoints.md
  explicação/         # Contexto e decisões
    por-que-escolhemos-esta-arquitetura.md

Passo 4: Comece a mover ou reescrever conteúdo existente para as categorias corretas. Não force conteúdo que serve a dois propósitos: divida-o.

⚠️
Atenção

Não tente migrar toda a doc de um projeto grande de uma vez. Comece pelo tutorial de introdução e pelos guias mais acessados, e va avançando secao por secao.

Exemplo prático: documentando uma biblioteca de autenticação

Imagine que você criou uma biblioteca Python de autenticação chamada fastauth. Sem Diataxis, e comum juntar tudo numa página README gigante. Com Diataxis, a estrutura ficaria assim:

Tutorial: "Proteja sua primeira rota em 5 minutos" - o leitor segue passo a passo, copia o código e ve funcionar. Sem desvios, sem explicações longas.

pip install fastauth

# main.py
from fastauth import protect

@protect(role="admin")
def minha_rota():
    return "Acesso liberado"

Guia prático: "Como configurar autenticação com Google OAuth" - assume que o leitor já instalou e quer resolver um cenário específico.

Referência: "API completa do decorator @protect" - lista todos os parâmetros, tipos aceitos, exceções lançadas e comportamento padrão. Sem exemplos longos, só os fatos.

Explicação: "Por que usamos JWT em vez de sessions" - conta o raciocínio por trás da decisão de design para quem quer entender a biblioteca em profundidade.

🚀
Pro tip

Adicione no topo de cada página uma linha indicando o tipo ("Este e um tutorial - você vai criar X"). Isso reduz a frustração do leitor que aterrissou na página errada.

Comparação com outras abordagens

Antes do Diataxis, as abordagens mais comuns eram: README monolítico, wiki sem estrutura, e "página por funcionalidade". Cada uma tem problemas conhecidos.

  • README monolítico: fácil de começar, impossível de navegar quando o projeto cresce. Tutorial, referência e contexto se misturam em blocos enormes.
  • Wiki sem estrutura: cada colaborador adiciona páginas do seu jeito, sem padrão. O resultado e um labirinto inconsistente.
  • Página por funcionalidade: organiza pelo produto, não pelo leitor. O usuário que quer aprender e o que quer consultar caem na mesma página.

O Diataxis vence quando você tem um projeto com mais de um perfil de usuário (iniciante vs avançado) e quando a doc e mantida por mais de uma pessoa. Ele da um critério objetivo para avaliar pull requests de documentação: "Isso e um tutorial ou um guia? Esta na pasta certa?"

Para projetos pequenos e pessoais sem público externo, um README bem escrito pode ser suficiente. O Diataxis brilha em projetos com contribuidores múltiplos e usuários em diferentes níveis.

Pontos positivos e limitações

O maior ponto positivo e também o mais subestimado: o Diataxis da uma linguagem comum para a equipe discutir documentação. Em vez de "essa doc e confusa", você consegue dizer "esse conteúdo mistura tutorial com referência, vamos separar".

  • Positivos: gratuito, agnosto de tecnologia, baseado em pesquisa com usuários reais, adotado por projetos reconhecidos, diagnóstico claro de problemas.
  • Limitações: não resolve problemas de tom, escrita ruim ou informação incorreta. E um framework de estrutura, não de qualidade do texto em si.

A maior crítica que você encontra na comunidade e que o Diataxis pode ser rígido para projetos muito específicos, como documentação de hardware ou processos internos de empresa. Nesses casos, os 4 tipos podem não mapear perfeitamente para o que a equipe precisa, e adaptações são necessárias.

🔴
Cuidado

Usar o Diataxis como desculpa para reescrever toda a doc antes de lançar e um erro clássico. Estrutura melhor não substitui conteúdo existente - comece a migrar, não a reescrever do zero.

Casos de uso reais

O Diataxis não e só para grandes frameworks open source. Qualquer equipe com docs públicas ou internas se beneficia.

  • Times de produto SaaS: separar o tutorial de onboarding ("crie sua primeira campanha em 10 minutos") da referência da API reduz chamadas ao suporte porque o usuário encontra o que precisa mais rápido.
  • Libraries open source: contribuidores sabem exatamente onde adicionar conteúdo novo, e revisores conseguem dar feedback objetivo ("isso é referência, vai na secao X").
  • Equipes de DevOps: runbooks e playbooks são guias práticos por definição. Separar guias de "como fazer" de explicações de "por que fazemos assim" facilita o onboarding de novos membros.
  • Ensino e cursos: instrutores que usam Diataxis conseguem identificar quando uma aula esta tentando ensinar e explicar ao mesmo tempo, tornando-a confusa.

Dicas e boas práticas

💡
Dica

Comece o tutorial sempre com uma frase do tipo "Ao final deste tutorial, você terá feito X". Isso define expectativa e mantém o foco no resultado prático.

💡
Dica

Na referência, evite exemplos longos. Se precisar de mais de 3 linhas de código para explicar um parâmetro, provavelmente ele pertence a um guia prático, não a referência.

🚀
Pro tip

Adicione um arquivo CONTRIBUTING.md na sua doc explicando os 4 tipos do Diataxis. Contribuidores externos vao saber onde adicionar o conteúdo deles sem precisar perguntar.

⚠️
Atenção

Explicação não e a mesma coisa que referência. Se você esta explicando uma decisão de design ou comparando abordagens, e explicação. Se esta descrevendo o que uma função faz e quais parâmetros aceita, e referência.

Vale a pena adotar o Diataxis?

Para qualquer projeto com mais de uma dezena de páginas de documentação e pelo menos dois perfis de usuário distintos (iniciante e avançado), o Diataxis vale a pena sem discussão.

O esforço de aprender o framework e de cerca de uma hora de leitura. A aplicação incremental pode começar no próximo PR que toca em documentação. O ganho e imediato: menos duvidas repetidas no suporte, mais contribuições externas úteis e uma equipe que consegue falar a mesma língua sobre docs.

Se você tem um projeto solo com README pequeno, o Diataxis e overkill. Mas se você já recebeu feedback de que sua doc e confusa ou se você mesmo já se perdeu tentando atualiza-la, esse framework e exatamente o que você precisa. Comece pelo site diataxis.fr ainda hoje.