Estrutura na Documentação
(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.)
Diátaxis não é apenas um sistema para estruturação de documentação. Trata-se de uma framework criada para compreender essa documentação, guiar o trabalho dos autores de documentação e avaliar a qualidade dessa documentação. Contudo, o seu impacto é mais notório quando se trata de estruturar documentação.
No âmbito do projecto Gatsby (da framework com o mesmo nome), reorganizámos recentemente a nossa documentação de código-> fonte aberto, e a framework Diátaxis foi o nosso principal recurso em todo o projecto. Os quatro quadrantes ajudaram-nos a privilegiar os objectivos do utilizador para cada tipo de documentação. Ao restruturarmos a nossa documentação tendo por base a > framework Diátaxis, ajudámos os utilizadores a encontrarem mais facilmente os recursos de que precisam quando precisam
- Megan Sullivan (@meganesulli
O problema da estrutura
De todos os problemas que apoquentam os autores e responsáveis por documentação, o problema da estrutura é um que representa uma proporção significativa das suas angústias. Existem múltiplas arquitecturas diferentes de documentação que tentam disponibilizar uma solução para este problema. Qualquer tentativa ordenada de organizar a documentação em categorias de conteúdo claras ajudará a melhorá-la (tanto para os autores como para os utilizadores).
No entanto, mesmo quando munidos de uma estrutura útil, os autores vêem-se muitas vezes na necessidade de escrever um determinado conteúdo de documentação que parece se situar fora da esquema da estrutura ou, em alternativa, para além dos seus limites internos.
O mapa
Diátaxis visa resolver este problema mediante a disponibilização de um esquema que prescreve uma estrutura de documentação baseada na descrição e análise sistemáticas das necessidades do utilizador (e não com base nas características do produto que a documentação visa servir, ou em torno dos tipos diferentes de coisas que o criador da documentação acha que precisam de ser ditas a respeito do produto).
Em vez de uma mera lista, Diátaxis disponibiliza um mapa de tipos distintos de documentação, especificando estes tipos de tal forma que a estrutura ajuda sempre organicamente a atribuir uma forma apropriada ao conteúdo.
O resultado é uma documentação que não só é melhor, como exige menos esforço para criar e manter.
Eixos do conhecimento
Importa compreender que Diátaxis se destina a ser aplicada à documentação relativa a um ofício prático, uma competência técnica - tal como a utilização de um produto. O exercício bem sucedido de tal ofício ou competência envolve tanto o domínio teórico (conhecimento e compreensão), como a capacidade de aplicar isso na prática, para trabalhar com as ferramentas e materiais do ofício.
Diátaxis divide a documentação em dois eixos de conhecimento: teoria/prática, e aquisição/aplicação.
Por conseguinte, a documentação ou contém conhecimentos teóricos ou descreve acções práticas, preocupando-se em servir ou a nossa aquisição ou a nossa aplicação de conhecimentos. Daí o mapa, através do qual as quatro formas de documentação se encontram dispostas:
Características da documentação
| Tutoriais | Guias de como-fazer | Referências | Explicações | |
|---|---|---|---|---|
| introduz, educa, conduz | guia, demontra | declara, descreve, informa | explica, esclarece, discute | |
| responde à questão | “Pode-me ensinar a…?” | "Como é que eu...?" | "O que é...?" | "Porquê...?" |
| orientado para | aprender | tarefas | informação | compreensão |
| finalidade | para permitir ao iniciado começar | para mostrar como resolver um problema específico | para descrever a maquinaria | para explicar |
| formato | uma lição | uma série de passos | descrição árida | explicação discursiva |
| analogia | ensinar uma criança a cozinhar | uma receita num livro de culinária | um artigo de referência numa enciclopédia | um artigo sobre história social culinária |
Uma vantagem clara de organizar os conteúdos desta forma é que fornece expectativas claras (ao leitor) e orientação (ao autor). Para além de explicitar a finalidade de qualquer conteúdo em particular, especifica também como este deve ser escrito e mostra onde deve ser colocado.
Cada conteúdo pertence a um tipo que tem não só uma função específica a desempenhar, como também essa função distingue-se e contrasta nitidamente das restantes funções da documentação.
Colapso da estrutura
A maioria dos sistemas e autores de documentação reconhecem pelo menos algumas destas distinções e tentam respeitá-las na prática. No entanto, existe uma espécie de afinidade natural entre cada uma das diferentes formas de documentação e os seus vizinhos no mapa, e uma tendência natural para esbater as distinções (o que pode ser constatado inúmeras vezes em exemplos de documentação).
tutoriais e guias de como fazer descrevendo ambos passos práticos. guias de como fazer e referências técnicas onde em ambos existe uma preocupação com a aplicação de conhecimentos. referências e explicações onde em ambas podemos encontrar conhecimentos teóricos. tutoriais e explicações onde ambos estão preocupados com a aquisição de conhecimentos.
O esbatimento destas distinções desencadeia problemas estruturais - sendo o mais frequente um choque total ou parcial entre tutoriais e guias de como fazer, enquanto as explicações se estendem tanto por tutoriais como por referências:
Mas, por vezes, a documentação tem, de facto, este aspecto:
O ciclo da interacção
Diátaxis destina-se a ajudar a documentação a servir melhor os utilizadores no seu ciclo de interacção com um produto.
Esta frase não deve ser entendida de forma demasiado literal. Não se trata de fazer com que o utilizador tenha de encontrar os diferentes tipos de documentação na ordem tutoriais > guias de como fazer > referências técnicas > explicações. Na prática, um(a) utilizador(a) real pode aceder à documentação a partir de qualquer ponto de entrada, em busca de orientação sobre algum assunto em particular. O que ele(a) pretende ler irá mudar a cada momento à medida que for consultando a documentação do seu projecto.
No entanto, a ideia de um ciclo de necessidades de documentação, que vai avançando por diferentes fases, é sólida e corresponde à forma como as pessoas se tornam de facto peritas num ofício. Por detrás desta ordenação existe um sentido e um significado específicos.
- Fase orientada para a aprendizagem: Começamos por aprender, e aprender uma competência significa mergulhar directamente no tópico - sob a orientação de um professor, se tivermos sorte.
- Fase orientada para tarefas: A seguir queremos aplicar na prática essa competência que acabámos de aprender.
- Fase orientada para a informação: Assim que o nosso trabalho exige recorrer a conhecimentos que ainda não temos na nossa cabeça, precisamos de consultar referências técnicas.
- Fase orientada para a explicação: Finalmente, longe da labuta profissional, reflectimos sobre aquilo que fizemos e os conhecimentos que assimilámos com vista a compreender o conjuntos dos aspectos relacionados com o ofício.
Uma vez aí chegados voltamos ao início, talvez para aprender uma coisa nova ou para explorar mais aprofundadamente o mesmo tema.
As quatro secções seguintes abordam em detalhe cada um dos quatro modos de documentação.