Tipos de conteúdo da documentação Quarkus
A documentação do Quarkus está estruturada em quatro tipos de conteúdo distintos: conceitos, instruções, tutoriais e referências. A composição e a estrutura dos documentos do Quarkus seguem a estrutura de documentação sistemática da Diátaxis para a criação de documentação técnica. Cada tipo de conteúdo atende a uma necessidade diferente do usuário, cumpre uma finalidade diferente e exige uma abordagem diferente para sua criação.
Estrutura de documentação da Diátaxis
Optamos por alinhar os documentos do Quarkus com a estrutura de documentação Diátaxis[1], que define uma estrutura central de conteúdo que atende às diferentes necessidades que os usuários têm ao consultar documentos.
Crédito da imagem: https://diataxis.fr/
O que vem a seguir é um breve resumo dos diferentes tipos de documentos, mas vale a pena ler se você quiser entender mais sobre o raciocínio por trás dessa classificação.
Guias conceptuais (Explicação)
A explicação é uma discussão que clarifica e esclarece um determinado tópico. A explicação é orientada para a compreensão.
Bons guias conceituais:
-
concentram-se na explicação de um tópico. Seu objetivo é ajudar o leitor a entender o conceito.
-
não ensine, instrua ou inclua informações de referência. Se precisar fazer referência a um tutorial, guia de instruções ou de referência, indique ao leitor onde ele pode encontrá-lo, mas não replique essas informações diretamente no seu guia conceitual.
-
fornecer informações básicas e contexto para explicar por que as coisas funcionam da maneira que funcionam ou por que foram construídas da maneira que são. Você pode citar decisões de projeto, razões históricas e restrições técnicas para reafirmar seus argumentos.
-
incluir exemplos específicos para ilustrar a explicação, mas evitar tornar a própria explicação muito dependente de uma tecnologia específica ou de um padrão de implementação.
-
analisar o conceito a partir de múltiplas perspectivas e estabelecer comparações com conceitos alternativos discutir se é relevante e útil para a compreensão do leitor.
-
pode expressar opiniões sobre as vantagens e desvantagens do conceito que está abordando em relação a diferentes casos de uso ou aplicações potenciais.
Guias de instruções
Os guias "como fazer" são instruções que conduzem o leitor através dos passos necessários para resolver um problema do mundo real. Os guias de instruções são orientados para objetivos.
Bons guias de instruções:
-
guiar (walk-through) ou demonstrar como completar uma tarefa.
-
assumir que tem contexto suficiente para iniciar a tarefa.
-
descrever as etapas concretas necessárias para concluir uma tarefa, mas essas etapas podem estar no meio de uma tarefa maior.
-
não explicar conceitos, eles dependem de outros documentos (como conceitos) para fazer isso.
-
são adaptáveis a casos de uso no mundo real.
-
são práticas (e não completas).
Guias de referência
Os guias de referência são descrições técnicas da máquina e do seu funcionamento. O material de referência é orientado para a informação.
Bons guias de referência:
-
são concisos e diretos. Afirmam, descrevem e informam.
-
são consistentes (na medida do possível) com outros guias de referência. Seguir o modelo ajuda nesse caso.
-
permanecem concentrados na descrição do tópico. Eles não explicam nem fornecem contexto adicional de outras fontes.
-
fornecer exemplos ou ilustrações que ajudem os leitores a compreender o que está sendo descrito.
-
são mantidos atualizados. Enquanto o material de referência de configuração é gerado, as referências de extensão que descrevem como a configuração deve ser aplicada devem ser precisas para serem úteis.
Tutoriais
Os tutoriais são lições que levam o leitor pela mão através de uma série de passos para completar um projeto de algum tipo. Os tutoriais são orientados para a aprendizagem.
Bons tutoriais:
-
proporcionar uma experiência de aprendizagem, dando ao leitor algo que ele possa fazer.
-
servem para iniciar o leitor (não criam um especialista).
-
fornecer ao leitor passos concretos a seguir, cada um com um resultado compreensível.
-
são fiáveis e coerentes (funcionam para todos os usuários, sempre).
-
incluem apenas informações suficientes para concluir a tarefa. Eles delegam a outros tipos de documentação (conceitos ou referência) para fornecer contexto adicional.
-
concentram-se em uma maneira de realizar a tarefa. Abordagens alternativas são exploradas em outros tipos de documentos (um guia de instruções, por exemplo).
