- Partindo da premissa de que a documentação técnica precisa cumprir papéis diferentes dependendo do contexto do usuário, o Diátaxis é uma abordagem que organiza em conjunto conteúdo, estrutura e formato
- Divide as necessidades do usuário em 4 tipos e as relaciona aos tipos de documentação tutorials, how-to guides, technical reference, explanation
- Não é apenas uma tabela de classificação, mas algo mais próximo de um framework de design de documentação que trata do que escrever, como escrever e onde posicionar cada conteúdo
- Também facilita para autores e mantenedores avaliar a qualidade da documentação, com a vantagem de ser leve, intuitivo e de não impor um modo específico de implementação
- Como nos casos da Vonage, Gatsby e Cloudflare, pode ser usado como critério prático por equipes que querem melhorar a navegabilidade da documentação e a estrutura da informação
Os 4 tipos de documentação definidos pelo Diátaxis
- Diátaxis é uma forma de pensar e de executar para criar e operar documentação técnica
- O ponto de partida é entender as necessidades de quem usa a documentação, e daí derivar princípios sobre conteúdo, arquitetura e formato
- As necessidades e os formatos da documentação são divididos em 4 categorias
-
tutorials
-
how-to guides
-
technical reference
- explanation
- A própria documentação também deve ser organizada em torno dessas 4 necessidades, e o Diátaxis trata de três perguntas ao mesmo tempo
- content: o que escrever
- style: como escrever
- architecture: como organizar
-
Aplicabilidade para autores e mantenedores
- O Diátaxis é uma abordagem útil não só para quem usa a documentação, mas também para quem a escreve e mantém
- É leve e fácil de entender
- Sua aplicação é intuitiva
- Não impõe restrições de implementação
- Fornece princípios de qualidade para que mantenedores consigam avaliar o próprio trabalho
- Os princípios foram consolidados com base em sua adoção bem-sucedida em centenas de projetos de documentação
Casos reais de projetos de documentação
- Greg Frileux, da Vonage, avaliou que com o Diátaxis foi possível criar um conjunto de documentação interna de que os usuários gostam e ao qual os colaboradores gostam de adicionar conteúdo
- A Gatsby usou o framework Diátaxis como um recurso principal ao reorganizar sua documentação open source, e afirmou que as 4 áreas ajudaram a priorizar os objetivos dos usuários em cada tipo de documentação
- A Cloudflare usou o Diátaxis como referência de arquitetura da informação no redesenho de Cloudflare developer docs e consulta o framework ao decidir onde novos conteúdos devem ser inseridos
1 comentários
Comentários do Hacker News
Mesmo não escrevendo profissionalmente, o insight mais importante e fundamental que tirei daqui, independentemente dos detalhes, é que não é preciso dizer tudo exatamente uma única vez.
Antes de entrar em contato com essa ideia, eu me enrolava achando que um único fluxo de texto precisava cumprir o papel de “documento inteiro”.
Só perceber que você pode escrever a mesma informação de formas diferentes para leitores diferentes já ajuda muito.
Como o leitor passa a procurar o denominador comum entre os exemplos, isso fica menos ambíguo do que explicar com apenas um exemplo.
Autores como Salomão, dos Provérbios bíblicos, também usam bastante essa técnica.
No resumo, você escreve “este artigo avalia Y em relação a Z e mostra que X se sustenta”; na introdução, explica que o problema A é importante por causa de B, mas que o aspecto X foi negligenciado, e que avaliar Y revela desafios práticos que Z não mostra; depois resume novamente: “em suma, Y é melhor que Z por causa de X”.
Também nos trabalhos relacionados, você continua dizendo que a abordagem de Z melhorou algo, mas que, como será mostrado adiante, não é suficiente; em cada seção, a mensagem central vai sendo retomada repetidamente, dando voltas ao redor dela.
Há duas semanas apliquei esse framework à documentação da Sequin, e só o fato de ter uma estrutura já foi muito bom.
Agora o fluxo da documentação ficou muito melhor, e ficou mais fácil adicionar e manter documentos porque sabemos onde colocar o quê.
Ironicamente, porém, a própria documentação do Diátaxis é um pouco difícil e prolixa; só peguei o jeito depois de ler algumas vezes.
Ao explicar para a equipe, usei a analogia de comprar um utensílio de cozinha como uma panela de pressão: primeiro você vê, no início rápido (tutorial), uma ideia geral de como ir de A a B; depois procura como fazer um prato específico de que gosta, que é o how-to; quando surgem dúvidas sobre detalhes, consulta a referência para conferir o tempo exato de cozimento de cada tipo de feijão; e, quando quer entender por que a pressão altera o tempo de cozimento ou como os dispositivos de segurança funcionam, lê o material explicativo.
Curiosamente, nossa documentação estava completamente ao contrário e começava com uma explicação como “How Sequin Works”.
O impulso natural de um engenheiro é primeiro falar dos princípios de funcionamento e de por que foi construído assim, para implantar um modelo mental, mas as pessoas não têm tempo nem paciência para isso.
É melhor conduzi-las pelo fluxo início rápido → how-to → referência, fazendo com que se acostumem ao mundo do produto, e só depois de realmente conquistar o interesse delas usar o material explicativo para convencê-las da abordagem.
https://sequinstream.com/docs
Muitas vezes a documentação fica vaga com bobagens como “experiência de sinergia inovadora”, como se a empresa tivesse vergonha de admitir que sua ferramenta é apenas uma ferramenta; ou, no extremo oposto, entra em detalhes específicos demais antes de tratar de “por que este produto existe”.
Dito isso, CDC aparece repetidamente na documentação e precisei pesquisar a definição. Implementei CDC várias vezes ao longo da carreira, mas não estava familiarizado com a sigla.
No fim, o fluxo é uma escolha do leitor; minha cabeça funciona querendo primeiro a explicação completa e depois procurando how-tos e tutoriais.
Do ponto de vista de um redator técnico, o Diátaxis é parecido com DITA: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
No entanto, sistemas desse tipo podem deixar passar aquilo de que o usuário realmente precisa.
Se a documentação técnica for usada apenas dentro de uma plataforma de documentação, o Diátaxis pode continuar se encaixando bem por muito tempo; mas, se a mesma informação puder e dever ser usada em vários lugares, como a UI, um portal de documentação e um aplicativo móvel, talvez seja necessário dividi-la em partes menores e montá-la de diferentes maneiras.
Isso é chamado de reutilização de conteúdo, ou seja, usar o mesmo conteúdo em vários locais.
Uma das abordagens para escrever e editar informações visando à reutilização de conteúdo é descrita no conceito de “every page is page one”: https://everypageispageone.com/the-book/
Se houver recursos e tempo, recomendo pesquisa de UX no início do projeto. Assim é possível evitar, mais tarde, uma situação sufocante causada por um modelo de informação restritivo demais.
A Nielsen/Norman também pesquisou bastante essa área e faz propostas interessantes para resolver problemas relacionados: https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA distingue tipos de tópico como tarefa, referência e conceito, mas tutoriais ou guias de solução acabam sendo combinações desses tipos de tópico.
Aqui o foco parece estar em entregáveis maiores do que tópicos individuais.
Também tenho curiosidade se, por você estar tão imerso em DITA, a complexidade não acaba sendo um problema.
Parece que dividir o conteúdo em partes reutilizáveis e marcá-las com a semântica de DITA ou DocBook tornaria muito mais fácil para modelos de linguagem grandes “entenderem” o material, mas nunca vi dados a respeito.
Hoje há maneiras melhores de escrever documentação do que ficar brigando com XSL/FO e seus parentes.
Na área de redação de documentação técnica, isso já é muito popular e está bem perto de ser um padrão
Mas há casos em que levam a ideia longe demais e deixam literalmente apenas essas quatro categorias nas páginas de documentação, o que em geral não funciona bem
É útil principalmente para ajudar o autor a manter em mente algo como “isto é um guia, então não vamos tentar ensinar; vamos focar em chegar ao resultado”
Na prática, fronteiras rígidas demais não são desejáveis, e não há problema em haver um pouco de tutorial dentro de um guia
Acho que o ponto em que essa abordagem realmente emperra é quando faltam conexões entre os quadrantes
Por exemplo, em um framework de software, se um guia não aponta para a referência da classe ou do método específico que você acabará tendo de usar, fica muito mais difícil explorar o contexto ao redor
Algumas documentações de frameworks específicas dividiram os quadrantes dessa forma, e essa é uma das coisas mais irritantes nelas
Se não houver outros especialistas por perto, pode ser melhor para um iniciante seguir as regras de forma estrita do que tentar “fazer a coisa certa por conta própria”
Por definição, o iniciante não tem a expertise para fazer esse julgamento; com a experiência, começa a enxergar os pontos em que deve se afastar das regras estabelecidas
É parecido com a diferença entre cozinhar em casa seguindo um livro de receitas e um chef profissional jogar ingredientes na panela com base em intuição e paladar
Mas já trabalhei com alguém que dizia que um tutorial não deveria ter nem uma frase explicativa sequer e que as regras tinham de ser seguidas literalmente
É aí que está o perigo desse tipo de sistema
É semelhante a princípios de programação como “não altere variáveis globais” ou “escreva funções curtas”
Não é preciso acertar perfeitamente, mas, na maior parte dos casos, é melhor se mover mais nessa direção do que na direção oposta
Então pedi ao Claude que classificasse a seção superior segundo o Diátaxis, e ele respondeu que era principalmente explicação, com alguns elementos de referência, e que não era ideal pelos critérios do Diátaxis
Disse que seria melhor separá-la em uma seção que explicasse puramente o conceito e a importância do ajuste de hiperparâmetros e outra seção de referência separada listando as ferramentas e métodos disponíveis
Mas em seguida também resumiu por que essa abordagem integrada funciona bem no contexto de um guia do usuário: ela segue o fluxo de como as pessoas realmente aprendem, conecta imediatamente conceitos e implementação, revela gradualmente desde os conceitos básicos até ferramentas complexas e entrega valor prático ao ligar teoria e prática
Tendo acabado de lançar meu primeiro app em SwiftUI, sinto fortemente que a documentação é tratada de forma muito descuidada na indústria de tecnologia moderna
Sinto muita falta do trabalho dos excelentes redatores técnicos que a Apple demitiu, e os engenheiros da Apple escrevem documentação muito mal
Dito isso, sempre tenho cautela com abordagens “dogmáticas”. É fácil surgir uma “classe sacerdotal” que não cede mesmo quando a realidade exige
As pessoas que criaram a doutrina originalmente a utilizam de forma brilhante, mas os “sacerdotes” que vêm depois às vezes estragam tudo e transformam a abordagem em uma maldição
Muitas boas ideias foram arruinadas por aplicações excessivamente rígidas. Basta ver no que “Agile” se transformou
A documentação tem basicamente duas faces, mantenedores e usuários, e suas necessidades são muito diferentes; provavelmente deveriam ser tratadas por equipes totalmente distintas
Também há o problema de documentações em vários lugares saírem de sincronia, mas o importante é o resultado
Se for possível sincronizar várias instâncias de forma eficaz, a documentação será efetiva e útil para o consumidor
Mesmo uma documentação perfeitamente formatada e sincronizada não tem valor se ninguém a lê
Em SNL, The Anal-Retentive Chef, interpretado por Phil Hartman, passava tanto tempo se preparando que não conseguia fazer a demonstração culinária de fato, e vejo muito disso na área técnica
Há casos em que a toolchain e as bibliotecas são perfeitas, mas, na prática, não dá para usá-las
Documentação é uma mistura de várias áreas: natureza humana e psicologia, design gráfico, arquitetura da informação, infraestrutura técnica, publicação e distribuição
Na maioria dos projetos, documentação é tratada como algo para depois, mas acredito que deveria ser uma consideração de primeira classe desde a fase de requisitos
Dá para mergulhar indefinidamente na estrutura da documentação, mas ele funciona como excelentes rodinhas de apoio até você encontrar os pontos de vazamento
Isso soa como dizer que mal-entendidos comuns ou aplicações incorretas de uma boa ideia estragam a própria ideia
Pelo contrário, há experiência a ganhar com a aplicação real. Se a ideia inicial na verdade não era boa, isso desfaz a ilusão; e maus exemplos, quando mal interpretados, expõem ambiguidades que levam ao fracasso e tornam a ideia mais refinada
Ainda assim, se muita gente se acostuma com implementações ruins, a popularidade da ideia pode cair e a demanda por implementações refinadas também pode diminuir
Isso está mais próximo de uma tragédia dos anticomuns do que da degeneração da própria ideia
O Diátaxis é excelente para estruturar documentação, mas seu verdadeiro valor está em simplificar a forma de escrever documentos
Ele nos tira da ideia de enfiar tudo em um único “documento perfeito” e nos faz reconhecer que usuários diferentes têm necessidades diferentes
Tutoriais servem para aprender acompanhando passo a passo; guias servem para resolver problemas específicos; referências servem para consulta rápida; explicações mergulham no “porquê”
Só essa clareza já pode levar à escrita de documentos úteis
Mas qualquer sistema vira uma armadilha se você se apegar a ele com rigidez excessiva
Ou será que existe um paradigma unificado?
Usamos essa abordagem na nossa organização e, desde a adoção, a documentação técnica subiu para um nível completamente diferente
Somando isso à propriedade das páginas e às revisões periódicas por cada responsável, tornou-se o único esforço de documentação técnica bem-sucedido que já vi
Acho que a figura que a Divio usa é muito mais intuitiva: https://docs.divio.com/documentation-system/
Só que o Diátaxis parece documentar cada significado de forma mais abrangente
A versão reescrita da Divio em Diataxis.fr tem gráficos menos poluídos, mas me parece essencialmente igual ao que a Divio usava
Sempre vi os dois materiais como, na prática, o mesmo documento no que diz respeito às ideias que apresentam no contexto de seus respectivos sites
Gostaria de saber em que ponto ela é mais intuitiva
Gosto desta ideia e tive a sorte de encontrar a pessoa que a criou algumas vezes na PyConUK. É uma pessoa talentosa e muito gentil
Dito isso, tenho ressalvas quanto a separar de forma tão rígida as várias áreas da documentação
Em um sprint, certa vez me disseram que a documentação que eu estava preparando era inaceitável porque misturava vários formatos. Para constar, não foi o Daniele quem disse isso
Não quero apelar para autoridade, mas trabalhei como professor por mais de 20 anos e tenho alguma noção de como explicar e estruturar o aprendizado para que as pessoas consigam realizar tarefas e, ao mesmo tempo, construir entendimento
Desde que não haja rigidez total, esta é uma excelente ferramenta para pensar em como criar documentação e decidir o que cada tipo de documento deve fazer
Em exemplos de documentação, como no numpy, vejo com frequência casos em que os exemplos poderiam ser escolhidos muito melhor, em vez de exemplos do tipo “mágica caída do céu”
Um único exemplo bem escolhido pode mostrar como usar algo e, ao mesmo tempo, ensinar muito sobre casos extremos ou pontos de atenção
Em teoria acho que faz sentido, mas tenho dificuldade em concordar. As palavras são próximas demais
Para mim, “tutorial”, “guia de como fazer” e “explicação” soam praticamente como sinônimos
Quando penso mais a fundo, entendo que há uma justificativa para cada categoria, mas elas são semanticamente tão próximas que meu cérebro não enxerga a diferença
Quando quero saber como algo funciona e vejo “tutorial” e “guia de como fazer”, não sei em qual clicar e acabo clicando no primeiro
Procurar termos que se ajustem melhor a você pode ser um exercício útil
Ou dá para entender pela distinção entre ação/cognição, ou seja, “fazer vs. pensar”, e aquisição/aplicação, ou seja, “em aprendizado vs. no trabalho”
Também há uma página dedicada a distinguir tutoriais de guias de como fazer: https://diataxis.fr/tutorials-how-to/
Uma das distinções mais simples é que tutorial é algo que não dá para fazer no Stack Overflow
Um tutorial segue um plano de aula definido pelo professor e preenche lacunas que o aluno nem sabe que tem
No Stack Overflow você precisa fazer uma pergunta, mas um tutorial é material para quem ainda nem sabe o que perguntar
Há muitas perguntas populares sobre como realizar tarefas simples, mas, para se encaixar nesse formato, é preciso fazer uma pergunta, não pedir ajuda de forma vaga: https://meta.stackoverflow.com/questions/284236
A documentação do Diátaxis explica a diferença de forma bastante eficiente: tutoriais são experiências orientadas ao aprendizado; guias de como fazer são instruções orientadas a objetivos; referências são descrições técnicas orientadas à informação; explicações são discussões orientadas ao entendimento
Nesse sistema, “tutorial” deve ser lido não como linguagem cotidiana, mas como termo técnico
É parecido com quando um psicólogo fala em “depression”, que não é exatamente o mesmo que o sentido cotidiano da palavra
Ainda assim, é melhor do que chamar de tutoriais Tipo I-IV
Uma palestra é explicação; um tutorial ou laboratório prático é uma experiência guiada, e me faz lembrar da empresa fictícia da Microsoft, a Contoso
Um guia de como fazer é o que você precisa quando procura uma solução ou pergunta ao ChatGPT, e referência é algo como um dicionário de sinônimos, uma enciclopédia ou um manual de uso
Videogames têm tutoriais embutidos, mas puzzles difíceis ainda exigem detonados, e as configurações de teclas são consultadas na referência