Diátaxis – uma abordagem sistemática para escrever documentação técnica

• Diátaxis é um conceito que propõe uma abordagem sistemática para a escrita de documentação técnica. Essa abordagem parte de um entendimento estruturado das necessidades dos usuários da documentação e propõe formas de abordar conteúdo, estrutura e formato.
• Derivado do grego antigo, Diátaxis identifica quatro necessidades claras e os formatos de documentação correspondentes: tutoriais, guias de como fazer, referência técnica e explicação. Propõe organizar a documentação de acordo com a estrutura dessas necessidades.
• Diátaxis resolve questões relacionadas ao conteúdo da documentação (o que escrever), ao estilo (como escrever) e à estrutura (como organizar).
• Tem valor não apenas para os usuários da documentação, mas também para quem a escreve e mantém. É leve, fácil de entender e simples de aplicar. Não impõe restrições de implementação e oferece princípios práticos para elevar a qualidade da documentação.

Conteúdo

• Este site está dividido em duas seções principais para ajudar na aplicação e compreensão do Diátaxis.

  • Comece por aqui. Estas páginas ajudam a entender a abordagem de forma imediata e concreta.
    • Aplicando Diátaxis
    • Tutoriais
    • Guias de como fazer
    • Referência
    • Explicação
    • Bússola
    • Fluxo de trabalho
  • Esta seção explora com mais profundidade a teoria e os princípios do Diátaxis, além de apresentar uma compreensão das necessidades que o sustentam.
    • Entendendo o Diátaxis
    • Fundamentos
    • Mapa
    • Qualidade
    • Tutoriais e guias de como fazer
    • Referência e explicação
    • Hierarquias complexas

• Diátaxis é um princípio comprovado na prática. Foi adotado com sucesso em centenas de projetos de documentação.

  • Na Gatsby, ao reorganizar a documentação open source, o framework Diátaxis foi usado como recurso principal. Os quatro quadrantes ajudam a priorizar os objetivos dos usuários para cada tipo de documentação.
  • Ao redesenhar a documentação para desenvolvedores da Cloudflare, o Diátaxis se tornou a estrela do norte da arquitetura da informação. Ao consultar o framework na hora de decidir onde posicionar novos conteúdos, a documentação ficou mais clara tanto para leitores quanto para contribuidores.

[GN⁺]

Comentários do Hacker News

• Um usuário mencionou que é importante perceber que não é necessário transmitir todas as informações de uma só vez. Escrever a informação de várias maneiras para diferentes leitores é útil.

• Foi explicado que aplicar o framework Diátaxis à documentação da Sequin melhorou o fluxo da documentação. No entanto, a própria documentação do Diátaxis foi considerada um tanto difícil e prolixa.

  • Foi usada como analogia a experiência de comprar um utensílio de cozinha.
    • Primeiro, consulta-se um tutorial de "início rápido" para entender o uso geral.
    • Descobrir como usá-lo para um prato específico é o "how-to".
    • Se quiser entender mais a fundo, procura-se o material de referência.
    • Se quiser compreender os princípios científicos do cozimento sob pressão, lê-se o material explicativo.

• Redatores de documentação técnica mencionaram que o Diátaxis é semelhante ao DITA. No entanto, explicaram que ele pode deixar passar as necessidades do usuário e que pode ser necessário dividir a informação em pequenas partes para reutilizá-la.

• Um usuário que desenvolveu um app em SwiftUI sente que a documentação técnica moderna é mal tratada e argumenta que a documentação deve considerar dois lados: o dos mantenedores e o dos usuários.

• Foi mencionado que o Diátaxis é útil para estruturar a documentação, mas que pode se tornar uma armadilha se for aplicado de forma rígida demais.

• Foi explicado que o verdadeiro valor do Diátaxis está em simplificar a forma de escrever documentação. É importante escrever a documentação de acordo com as necessidades de cada usuário.

• Foi mencionado que o gráfico da divio é mais intuitivo, mas que o Diátaxis oferece uma documentação mais abrangente.

• Foi explicado que, após adotar o Diátaxis, a documentação técnica melhorou bastante, e que a propriedade das páginas e revisões periódicas contribuíram para uma documentação bem-sucedida.

• Foi mencionado que o framework Diátaxis oferece uma estrutura simples e fácil de entender, sendo útil para a escrita de documentação técnica.

• Alguém está escrevendo a documentação do Logdy usando o Diátaxis e pede opiniões sobre se esse método é útil para documentar produtos de software. Também explicou que conseguiu transmitir de forma eficaz como usar o produto por meio de posts de blog.