Quarkus documentation concepts
Overview of concepts underlying the structure and composition of Quarkus docs.
Content Types
We are aligning Quarkus docs with the Diátaxis documentation framework[1], which defines a core content structure that addresses the different needs users have when consulting docs. What follows is a brief summary of the different document types, but their site is worth a read if you want to understand more of the reasoning behind this classification.
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.
-
provide background information and context to explain why things work the way they do, or why they are built in a particular way. You can cite design decisions, historical reasons, and technical constraints to reaffirm your points.
-
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.
How-To guides
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.
-
focus on one way of doing the task. Alternative approaches are explored in other document types (e.g. a how-to guide).
