A Framework Diátaxis

(Conteúdo original retirado e Diataxis.fr e utilizado aqui com o consentimento do autor nos termos de uma licença CC-BY-SA 4.0.)

---

UMA FRAMEWORK SISTEMÁTICA PARA A AUTORIA DE DOCUMENTAÇÃO TÉCNICA.

A framework Diátaxis visa resolver o problema de como estruturar documentação técnica. Tem como objectivo compreender as necessidades dos utilizadores de documentação no decurso da sua interacção com um produto mediante a adopção de uma abordagem sistemática.

A Grande Teoria Unificada da Documentação

- David Laing

Quatro modos de documentação

A framework identifica quatro modos de documentação - tutoriais, guias de como-fazer, referências técnicas e explicações.

Cada um destes modos (ou tipos) responde a diferentes necessidades do utilizador, cumpre uma finalidade diferente e requer uma abordagem diferente para a sua criação.

A documentação técnica deve ser estruturada explicitamente tendo por base estes quatros tipos e deve mantê-los todos separados e distintos uns dos outros.

Por outras palavras, o que nós designamos de documentação não consiste na sua essência numa única coisa mas sim quatro. Compreender as implicações disto e a forma como estes quatro diferentes elementos funcionam pode na maior parte dos casos ajudar a melhorar a documentação.

Diátaxis promete não só melhorar a qualidade da documentação e dos projectos mas também aumentar os níveis de sucesso das equipas envolvidas.

Quando estávamos a reelaborar a documentação para programadores da Cloudflare developer, esta framework para conteúdos serviu de nosso guia em termos de arquitectura de informação. Quando não tinhamos a certeza de onde é que um novo conteúdo se devia enquadrar, íamos consultar a framework. A nossa documentação nunca foi tão facilmente compreensível como hoje, tanto por leitores como por colaboradores

- Adam Schwartz (@AdamSchwartz)

Leve e de fácil adopção

A framework é leve, fácil de compreender e simples de aplicar. Não impõe restrições de implementação.

Completa e abrangente

Diátaxis proporciona um esquema abrangente e de aplicação quase universal, com resultados comprovados na prática numa grande variedade de sectores e aplicações. Neste grupo incluem-se projetos de documentação tanto grandes como pequenos, abertos ou proprietários.

Vídeo de apresentação

Em baixo poderá ver um vídeo de uma palestra realizada na conferência PyCon Australia 2017 onde são apresentados os conceitos por detrás de Diátaxis: