Nem toda documentação serve para o mesmo propósito. Um guia passo a passo que guia alguém por um processo faz um trabalho completamente diferente de um artigo de referência que define uma lista de parâmetros. Usar o tipo de conteúdo errado para uma tarefa é uma das razões mais comuns pelas quais a documentação falha com os leitores — mesmo quando a informação em si é precisa.
Este artigo descreve cinco tipos principais de conteúdo usados em uma base de conhecimento bem estruturada, explica o trabalho de cada um e ajuda você a reconhecer qual tipo é adequado para cada necessidade. Os quatro primeiros são baseados no amplamente utilizado framework Diátaxis (tutoriais, guias práticos, referência e explicação); A solução de problemas é adicionada aqui como um quinto, já que o conteúdo diagnóstico se comporta de forma suficientemente diferente de ambos para merecer sua própria definição.
Os Cinco Tipos Principais de Conteúdo
Guias práticos
Um guia prático guia o leitor por uma tarefa específica do início ao fim. Pressupõe que o leitor tem um objetivo e sabe por que quer alcançá-lo — ele só precisa saber como. Todo o artigo é organizado em torno de etapas de ação que produzem um resultado concreto.
| O trabalho que ele faz | Permite ao leitor realizar uma tarefa do mundo real. |
| Quando usá-lo | Sempre que um leitor precisar fazer algo específico — configurar um recurso, configurar uma configuração, completar um fluxo de trabalho. |
| O que não é | Um tutorial (que ensina), uma referência (que informa) ou um artigo conceitual (que explica). Um guia prático não ensina conceitos; Ele conduz o leitor por etapas. |
| Reconhecível por | Um título orientado a tarefas ("Como configurar autenticação em dois fatores"), passos numerados, um ponto de partida definido e um resultado definido. |
Tutoriais
Um tutorial ensina o leitor a fazer algo fazendo com que ele faça. O objetivo é aprender, não completar tarefas. O leitor segue um tutorial para desenvolver compreensão e habilidade, não porque tenha uma necessidade imediata no mundo real. O tutorial controla o ambiente — pode usar dados de exemplo, um sandbox ou um cenário simplificado especificamente projetado para aprendizado.
Nota de escopo: Na prática, essa categoria é fácil de ser usada em excesso. Se sua base de conhecimento não oferece realmente um sandbox, conjunto de dados de exemplo ou caminho dedicado de integração, a maior parte do conteúdo rotulado como "tutorial" é na verdade um guia disfarçado — o leitor tem uma tarefa real em mente, não um objetivo de aprendizado abstrato. Reserve o "tutorial" para conteúdo que realmente ensine em um ambiente controlado; caso contrário, escreva um guia prático.
| O trabalho que ele faz | Constrói competência e confiança em um novo usuário. |
| Quando usá-lo | Ao integrar novos usuários, introduzir um recurso complexo ou ajudar leitores a desenvolver habilidades que ainda não possuem — genuinamente por meio de um ambiente controlado e focado no aprendizado. |
| O que não é | Um guia prático (que resolve uma tarefa real), ou um artigo conceitual (que explica sem precisar fazer). Um tutorial sempre envolve ação — o leitor precisa fazer algo. |
| Reconhecível por | Um enquadramento orientado para o aprendizado ("Neste tutorial, você vai aprender como..."), um ambiente controlado ou de amostra, e uma declaração explícita do que o leitor será capaz de fazer ao final. |
Artigos conceituais
Um artigo conceitual explica como algo funciona, o que é algo ou por que algo é projetado da forma como é. Ela não instrui — ela informa. O leitor sai com compreensão, não com uma tarefa concluída.
| O trabalho que ele faz | Constrói o modelo mental que o leitor precisa para usar um produto de forma eficaz. |
| Quando usá-lo | Ao apresentar um novo conceito, explicar a arquitetura de um sistema ou ajudar o leitor a entender o raciocínio por trás de uma decisão de design antes de interagir com ela. |
| O que não é | Um guia ou tutorial prático. Um artigo conceitual nunca tem etapas numeradas. Explica; Não instrui. |
| Reconhecível por | Um título orientado a conceito ("Compreendendo controle de acesso baseado em papéis"), conteúdo carregado de prosa, diagramas e exemplos, e a ausência de etapas procedimentais. |
Artigos de referência
Um artigo de referência fornece informações precisas e estruturadas que os leitores consultam, não lêem sequencialmente. É um recurso consultado no meio de uma tarefa, não lido do começo ao fim. Artigos de referência priorizam a completude e a precisão em detrimento do fluxo narrativo.
| O trabalho que ele faz | Oferece aos leitores acesso rápido a informações técnicas precisas e completas. |
| Quando usá-lo | Documentação da API, listas de parâmetros, atalhos de teclado, definições de código de erro, glossários, opções de configuração — qualquer lugar que um leitor precise consultar algo. |
| O que não é | Um tutorial ou guia prático. Artigos de referência não guiam os leitores por um processo. Eles fornecem informações; O leitor decide o que fazer com ela. |
| Reconhecível por | Um formato estruturado e previsível (tabelas, listas de definições, blocos de código), um padrão consistente entre as entradas e um título que sinaliza comportamento de busca ("referência de API", "Atalhos de teclado"). |
Artigos sobre solução de problemas
Um artigo de solução de problemas ajuda o leitor a diagnosticar e resolver um problema. Ele é organizado em torno dos sintomas e suas soluções, não das características do produto. Um leitor chega porque algo está errado — o trabalho do artigo é ajudá-lo a identificar o que é e corrigir.
Diferente de um guia prático, que começa com um objetivo ("Quero realizar X"), um artigo de solução de problemas começa com um sintoma ("X não está funcionando"). Essa distinção — objetivo em primeiro lugar versus sintoma primeiro — é o motivo pelo qual o conteúdo de solução de problemas ganha sua própria categoria aqui, em vez de ser incluído em guias práticos.
| O trabalho que ele faz | Resolve um problema que o leitor está vivenciando ativamente. |
| Quando usá-lo | Mensagens de erro, comportamentos inesperados, processos falhados, problemas comuns de suporte. |
| O que não é | Um guia prático (que assume que as coisas estão funcionando) ou um artigo de referência (que fornece informações sem resolver um problema específico). Um artigo de solução de problemas é diagnóstico — começa com um sintoma, não com um objetivo. |
| Reconhecível por | Organização centrada nos sintomas ("Se você vê... / Se você não pode..."), lógica condicional, múltiplas causas possíveis para um único sintoma e caminhos de escalonamento quando as soluções do artigo não resolvem o problema. |
Conteúdo que não se encaixa perfeitamente
Esses cinco tipos cobrem a maior parte de uma base de conhecimento, mas não toda. Conteúdo como FAQs, glossários, notas de lançamento e visão geral de produtos ou páginas de destino frequentemente se inspira em mais de um tipo sem corresponder totalmente a nenhum deles — uma FAQ, por exemplo, se comporta como um artigo de referência (pesquisado, não lido do início ao fim), mas é organizado em torno de perguntas em vez de um esquema estruturado. Trate-os como exceções reconhecidas por si só, em vez de forçá-los a uma das cinco categorias; O que importa é que cada conteúdo tenha uma função clara e única, seja lá como você chame.
Mistura de Tipos de Conteúdo
Na prática, um único artigo pode se basear em mais de um tipo de conteúdo. Um guia prático pode incluir um breve parágrafo conceitual para explicar por que um passo é importante. Um artigo de solução de problemas pode incluir uma tabela de referência com códigos de erro.
Isso é aceitável, desde que o objetivo principal do artigo permaneça claro. Os leitores precisam ser capazes de identificar imediatamente que tipo de artigo estão lendo e o que vão tirar dele. Um artigo que tenta ao mesmo tempo ensinar, instruir, explicar e resolver problemas não fará nada disso bem.
Quando um artigo começa a servir a muitos propósitos, divida-o.
Escolhendo o Tipo de Conteúdo Certo
Quando você se sentar para escrever um novo artigo, faça uma pergunta primeiro: o que meu leitor precisa para sair de lá?
| O leitor precisa sair daqui com... | Escreva um... |
|---|---|
| Uma tarefa concluída | Guia prático |
| Uma nova habilidade ou compreensão, adquirida ao fazer | Tutorial |
| Um modelo mental ou explicação | Artigo conceitual |
| Uma informação específica | Artigo de referência |
| Um problema resolvido | Artigo sobre solução de problemas |
Acertar isso antes de começar a escrever economiza bastante tempo de revisão depois. Um tipo de conteúdo bem escolhido dá ao artigo sua forma; Uma escolha mal escolhida significa reescrever do zero.