Comece aqui - Diátaxis em cinco minutos
Você não precisa ler tudo neste site para entender o Diátaxis ou para começar a usá-lo na prática. Na verdade, recomendo que não o faça. A melhor maneira de começar a usar o Diátaxis é aplicando-o — a algo, por menor que seja.
Leia esta página para uma breve introdução. Cada seção contém links para materiais mais detalhados; consulte-os quando precisar — quando estiver trabalhando ou refletindo sobre os problemas de documentação que encontrou.
Os quatro tipos de documentação
A ideia central do Diátaxis é que existem fundamentalmente quatro tipos identificáveis de documentação que respondem a quatro necessidades diferentes. Os quatro tipos são: tutoriais, guias práticos, referência e explicação. Cada um tem um propósito diferente e precisa ser escrito de uma maneira diferente.
Tutoriais
Um tutorial é uma lição que guia o estudante pela mão através de uma experiência de aprendizado. Um tutorial é sempre prático: o usuário faz algo, sob a orientação de um instrutor. O tutorial é projetado em torno de um contato que o aprendiz possa compreender, no qual o instrutor é responsável pela segurança e sucesso do aprendiz.
Uma aula de direção é um bom exemplo de tutorial. O objetivo da lição é desenvolver habilidades e confiança no estudante, não ir do ponto A ao ponto B. Um exemplo de software poderia ser: Vamos criar um jogo simples em Python.
O usuário aprenderá por meio do que faz — não porque alguém tentou ensiná-lo.
Na documentação, a dificuldade especial é que o instrutor está condenado a estar ausente, não estando presente para monitorar o aprendiz e corrigir seus erros. O instrutor deve, de alguma forma, encontrar um meio de se fazer presente apenas através da instrução escrita.
Guias práticos
Um guia prático aborda um objetivo ou problema do mundo real, fornecendo instruções práticas para ajudar o usuário que está nessa situação.
Um guia prático sempre se direciona a um usuário que já é competente, de quem se espera que seja capaz de usar o guia para ajudá-lo a realizar seu trabalho. Em contraste com um tutorial, um guia prático está preocupado com o trabalho em vez do estudo.
Um guia prático pode ser: Como armazenar filme de nitrato de celulose (em fotografia cinematográfica) ou Como configurar o perfilamento de quadros (em software). Ou até mesmo: Solução de problemas de implantação (troubleshooting).
Referência
Os guias de referência contêm a descrição técnica — fatos — que um usuário precisa para fazer as coisas corretamente: informações precisas, completas e confiáveis, livres de distrações e interpretações. Eles contêm conhecimento proposicional ou teórico, não guias para ação.
Assim como um guia prático, a documentação de referência atende ao usuário que está no trabalho, e cabe a ele ser suficientemente competente para interpretá-la e utilizá-la corretamente.
O material de referência é neutro. Ele não se preocupa com o que o usuário está fazendo. Uma carta náutica poderia ser usada pelo navegador de um navio para traçar uma rota, mas igualmente bem por um magistrado de acusação em um processo judicial.
Onde for possível, a arquitetura da documentação de referência deve refletir a estrutura ou arquitetura da coisa que está descrevendo — exatamente como um mapa faz. Se um método faz parte de uma classe que pertence a um determinado módulo, devemos esperar ver essa mesma relação também na documentação.
Explicação
Os guias explicativos fornecem contexto e histórico. Eles atendem à necessidade de compreender e colocar as coisas em uma perspectiva mais ampla. A explicação conecta os pontos e ajuda a responder à pergunta por quê?
A explicação muitas vezes precisa rodear seu assunto e abordá-lo de diferentes direções. Pode conter opiniões e adotar perspectivas.
Assim como a referência, a explicação pertence ao reino do conhecimento proposicional, e não da ação. No entanto, seu propósito é servir ao estudo do usuário — como fazem os tutoriais — e não ao seu trabalho.
Frequentemente, escritores de tutoriais ansiosos para que seus alunos saibam coisas sobrecarregam seus tutoriais com explicações distrativas e inúteis. Seria muito mais útil dar ao aprendiz a explicação mínima possível (“Aqui, usamos HTTPS porque é mais seguro”) e, em seguida, criar um link para um artigo detalhado (Comunicação segura usando criptografia HTTPS) para quando o usuário estiver pronto para isso.
O mapa do Diátaxis
Os quatro tipos de documentação e as relações entre eles podem ser resumidos no mapa do Diátaxis.
O Diátaxis não é apenas uma lista de quatro coisas diferentes, mas um arranjo conceitual delas. Ele mostra como os quatro tipos de documentação estão relacionados entre si e como são distintos uns dos outros.
Cruzar ou confundir os limites descritos no mapa está no cerne de um grande número de problemas na documentação.
A bússola do Diátaxis
Como você pode ver pelo mapa:
-
tutoriais e guias práticos estão preocupados com o que o usuário faz (ação)
-
referência e explicação tratam do que o usuário sabe (cognição)
Por outro lado:
-
tutoriais e explicação servem à aquisição de habilidades (o estudo do usuário)
-
guias práticos e referência servem à aplicação de habilidades (o trabalho do usuário)
Mas um mapa não diz o que fazer — ele é uma referência. Para guiar sua ação, você precisa de um tipo diferente de ferramenta, neste caso, uma espécie de bússola do Diátaxis.
A bússola é útil de duas formas diferentes.
Ao criar documentação, ela ajuda a esclarecer suas próprias intenções e a garantir que você está realmente fazendo o que pensa que está fazendo.
Ao analisar a documentação, ela ajuda a entender o que está acontecendo nela e faz com que os problemas fiquem evidentes.
A bússola não é nem de longe tão chamativa quanto o mapa, mas quando você estiver trabalhando e quebrando a cabeça com um problema de documentação, ela é o que ajudará você a seguir em frente.
| Se o conteúdo... | ...e serve ao/à do usuário... | ...então ele pertence a... |
|---|---|---|
| informa a ação | aquisição de habilidades | um tutorial |
| informa a ação | aplicação de habilidades | um guia prático |
| informa a cognição | aplicação de habilidades | referência |
| informa a cognição | aquisição de habilidades | explicação |
Processo de Trabalho
Existe um fluxo de trabalho muito simples para o Diátaxis.
-
Considere o que você vê na documentação, bem na sua frente agora (o que pode ser literalmente nada, se você ainda não começou).
-
Pergunte-se: existe alguma maneira de melhorar isso?
-
Decida uma coisa que você poderia fazer agora, por menor que seja, para melhorá-lo.
-
Faça essa coisa.
E então repita.
É isso.
Faça o que preferir
Você pode fazer o que preferir com o Diátaxis. Não precisa acreditar nele e não há exame. É uma abordagem totalmente pragmática. Eu acredito que seja verdadeiro, mas o que importa é que ele realmente ajuda as pessoas a criarem documentações melhores. Se você encontrar uma ideia ou percepção nele que pareça valer a pena, aproveite-a.
Existe uma teoria extensamente elaborada em torno do Diátaxis, mas você não precisa aderi-la, nem mesmo ler sobre ela. O Diátaxis não exige um compromisso de segui-lo até o fim.
Você pode fazer apenas uma coisa agora e, mesmo que nunca mais faça nada depois, terá pelo menos feito essa melhoria única. (Na prática, o que você descobrirá é que cada coisa que faz lhe dará uma pista sobre a próxima coisa a ser feita — você só precisa continuar fazendo-as.)
Comece
Neste ponto, você já leu tudo o que precisa para começar a usar o Diátaxis.
Você pode ler mais se quiser e, eventualmente, provavelmente deveria, mas você obterá o máximo de valor da orientação deste site quando recorrer a ele com um problema ou uma dúvida. É aí que ele ganha vida.