Comece aqui - Diátaxis em cinco minutos
Você não precisa ler tudo neste site para compreender o Diátaxis ou para começar a utilizá-lo na prática. Na verdade, recomendamos que não o faça. A melhor maneira de começar com 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 material mais aprofundado; consulte-os quando necessário - quando estiver realmente 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 (how-to guides), referência e explicação. Cada um tem um propósito diferente e precisa ser escrito de maneira distinta.
Tutoriais
Um tutorial é uma aula, que conduz o aluno 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. Um tutorial é projetado em torno de uma experiência que o aluno pode compreender, na qual o instrutor é responsável pela segurança e pelo sucesso do aluno.
Uma aula de direção é um bom exemplo de tutorial. O objetivo da aula é desenvolver habilidades e confiança no aluno, e não ir de A a B. Um exemplo de software poderia ser: Vamos criar um jogo simples em Python.
O usuário aprenderá através do que faz - não porque alguém tentou lhe ensinar.
Na documentação, a dificuldade especial é que o instrutor está condenado a estar ausente e não está lá para monitorar o aluno e corrigir seus erros. O instrutor deve, de alguma forma, encontrar uma maneira de estar presente apenas por meio de instruções escritas.
Guias práticos
Um guia prático aborda um objetivo ou problema do mundo real, fornecendo orientações práticas para ajudar o usuário que se encontra nessa situação.
Um guia prático sempre se dirige a um usuário que já é competente, do qual se espera que seja capaz de usar o guia para 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 (na cinematografia) ou Como configurar o perfil de quadros (em software). Ou até mesmo: Solução de problemas de deploy.
Referência
Os guias de referência contêm a descrição técnica - fatos - que o usuário precisa para fazer as coisas corretamente: informações precisas, completas, confiáveis, livres de distrações e interpretações. Eles contêm conhecimento proposicional ou teórico, e não guias de ação.
Assim como um guia prático, a documentação de referência atende ao usuário que está no trabalho, e cabe ao usuário 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 pode ser usada pelo navegador de um navio para traçar uma rota, mas igualmente bem por um magistrado de acusação em um caso legal.
Sempre que possível, a arquitetura da documentação de referência deve refletir a estrutura ou arquitetura da coisa que está descrevendo - assim como faz um mapa. Se um método faz parte de uma classe que pertence a um determinado módulo, devemos esperar ver o mesmo relacionamento na documentação também.
Explicação
Os guias explicativos fornecem contexto e histórico. Eles atendem à necessidade de compreender e colocar as coisas em um panorama mais amplo. A explicação une as coisas e ajuda a responder à pergunta por quê?
A explicação frequentemente precisa girar em torno de seu assunto e abordá-lo de diferentes direções. Ela 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, os autores de tutoriais que estão ansiosos para que seus alunos saibam das coisas sobrecarregam seus tutoriais com explicações distrativas e inúteis. Seria muito mais útil fornecer ao aluno a explicação mais mínima (“Aqui, usamos HTTPS porque é mais seguro”) e, em seguida, criar um link para um artigo aprofundado (Comunicação segura usando criptografia HTTPS) para quando o usuário estiver pronto para ele.
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 são distintos uns dos outros.
Cruzar ou borrar as fronteiras descritas no mapa está no centro de um vasto número de problemas na documentação.
A bússola do Diátaxis
Como você pode ver no mapa:
-
os tutoriais e guias práticos estão preocupados com o que o usuário faz (ação)
-
a referência e a explicação tratam do que o usuário sabe (cognição)
Por outro lado:
-
os tutoriais e a explicação servem à aquisição de habilidades (estudo do usuário)
-
os guias práticos e a referência servem à aplicação de habilidades (trabalho do usuário)
Mas um mapa não diz o que fazer - ele é uma referência. Para orientar 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 maneiras 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 estar fazendo.
Ao examinar a documentação, ela ajuda a entender o que está acontecendo nela e faz com que os problemas se
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 que o ajudará a avançar.
| Se o conteúdo… | …e serve ao… | …então ele deve pertencer 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 |
Trabalhando
Existe um workflow muito simples para o Diátaxis.
-
Considere o que você vê na documentação à sua frente agora mesmo (o que pode ser literalmente nada, se você ainda não começou).
-
Pergunte-se: há alguma maneira de ela ser melhorada?
-
Decida sobre uma coisa que você pode fazer nela agora mesmo, por menor que seja, que a melhore.
-
Faça essa coisa.
E então repita.
É isso.
Faça o que quiser
Você pode fazer o que quiser com o Diátaxis. Você não precisa acreditar nele e não há exame. É uma abordagem totalmente pragmática. Acreditamos que ele seja verdadeiro, mas o que importa é que ele realmente ajuda as pessoas a criarem uma documentação melhor. 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 aderir a ela ou sequer ler sobre ela. O Diátaxis não exige um compromisso de segui-lo até um fim definitivo.
Você pode fazer apenas uma coisa, agora mesmo, e mesmo que não faça mais nada depois disso, você terá pelo menos feito essa única melhoria. (Na prática, o que você descobrirá é que cada coisa que fizer lhe dará uma pista sobre a próxima coisa a fazer - você só precisa continuar fazendo-as.)
Comece
Neste ponto, você leu tudo o que precisa para começar com o Diátaxis.
Você pode ler mais se quiser, e eventualmente provavelmente deveria, mas você obterá o máximo valor da orientação deste site quando recorrer a ele com um problema ou uma pergunta. É aí que ele ganha vida.