Documentação e base de conhecimento

O que esta categoria cobre

Lugares para registrar as coisas por escrito de modo que outras pessoas as encontrem: centrais de ajuda voltadas para o cliente, manuais internos, documentação para desenvolvedores e a busca que torna qualquer um deles útil.

A distinção que importa é o público. A documentação para clientes precisa de um endereço público, de um processo de revisão e de uma linguagem escrita para quem já está travado. A documentação para a equipe pode ser mais bagunçada e precisa de permissões.

O conhecimento pessoal e de pequenas equipes pertence a notas e wiki. A fila de tickets onde chegam as perguntas sem resposta é atendimento ao cliente.

A estrutura decide se algo será encontrado

Todo projeto de documentação começa organizado e termina como uma pilha. A ferramenta pode retardar isso ou acelerá-lo.

Veja como a hierarquia funciona: categorias, subpáginas, links cruzados e se uma página pode ficar em dois lugares sem ser duplicada. Depois veja o que acontece com trezentas páginas, que é onde uma navegação pensada para trinta desmorona.

A busca é o teste honesto. Tente uma consulta com as palavras que um cliente usaria, e não com o seu vocabulário interno. Os produtos que só encontram títulos vão falhar nesse teste, e os leitores acabarão na sua fila de suporte.

Tags e sugestões de artigos relacionados ajudam quando são mantidas. Ninguém as mantém à mão por muito tempo, então prefira produtos que geram as conexões a partir do conteúdo.

Escrita, revisão e manter as páginas verdadeiras

A documentação apodrece em silêncio. Uma página que estava correta em março é um ticket de suporte em setembro, e nada nela parece errado.

Os produtos úteis trazem responsável, datas de revisão e um carimbo de última conferência que o leitor pode ver. Estados de rascunho e fluxo de revisão importam quando mais de duas pessoas escrevem, e o histórico de versões importa na primeira vez que alguém pergunta o que uma página dizia antes de mudar.

Vale conferir também o reaproveitamento. Um limite, um preço ou uma lista de versões compatíveis deve existir uma única vez e ser incluído em todos os lugares onde aparece, em vez de colado em onze páginas que vão divergir até o próximo trimestre.

Publicação e a questão das buscas

Uma central de ajuda pública é um site e deve se comportar como tal.

• URLs limpas que sobrevivam a uma reorganização, com redirecionamentos quando não puderem.
• Títulos e descrições editáveis por artigo, e não gerados a partir da primeira linha.
• Páginas rápidas, sem uma aplicação pesada carregando antes de o texto aparecer.
• Sitemaps que se atualizam quando você publica, e não num horário que ninguém lembra.
• Um domínio próprio, para que o material construa autoridade para o seu site em vez de para o do fornecedor.

Esse último ponto vale ser defendido internamente. A documentação costuma ser o conteúdo de melhor desempenho que uma empresa de software tem, e hospedá-la num subdomínio do fornecedor entrega esse tráfego.

Medição e a única métrica que importa

As visualizações de página não dizem quase nada. Dois números dizem muito.

O primeiro são as buscas que não retornaram nenhum resultado útil, que formam uma lista escrita do que criar em seguida. O segundo é se os leitores que abriram um artigo ainda entraram em contato com o suporte depois, o que exige conectar a central de ajuda ao seu sistema de tickets.

Reescreva a partir dessa lista, e não a partir de opinião. Os cinco artigos que mais falham merecem mais atenção do que cinquenta que ninguém visita.

Como esses produtos são cobrados

Licenças para autores, às vezes leitura gratuita para todos, às vezes por leitor interno cadastrado. As centrais de ajuda públicas costumam cobrar por autor e por volume de artigos, e as wikis internas, por usuário.

Observe três fronteiras. Domínios próprios, versionamento e login único tendem, cada um, a ficar um plano acima do de entrada. A profundidade da análise é uma quarta. Os fornecedores que agrupam uma central de ajuda com um produto de suporte costumam precificá-la como um complemento, e não incluí-la, o que é um dos hábitos reunidos em o que as páginas de preços escondem.

Antes de se comprometer, exporte tudo e leia o resultado. Markdown ou marcação limpa significa que você pode sair. Um formato proprietário significa que o arquivo é refém.

Começar uma central de ajuda do zero

A primeira versão deve ser constrangedoramente pequena.

Pegue as vinte perguntas que a sua fila de suporte mais recebe e responda a elas direito. Isso cobre a maioria dos contatos e leva uma semana, enquanto planejar primeiro uma estrutura completa leva um trimestre e não responde a nada nesse meio-tempo.

Escreva cada artigo para alguém que já está travado, o que significa a resposta primeiro e a explicação depois. As capturas de tela envelhecem mal, então use-as onde ajudam de verdade e espere ter de substituí-las.

Depois deixe a estrutura surgir. Com trinta artigos as categorias ficam óbvias, e impô-las no quinto artigo significa reorganizar de qualquer jeito.

Publique os termos de busca que não retornaram nada como a sua fila de escrita. É o único plano de conteúdo desta categoria que nunca acaba e nunca erra.