Avaliar Discernir
Discernir as principais qualidades do produto e, se for caso disso, compará-lo com outros.
Os utilizadores da documentação são também potenciais clientes ou avaliadores. Um produto ou projeto de software prospera quando o número de utilizadores ativos aumenta. Quem lê a documentação deve conseguir discernir as principais qualidades do produto e, se for caso disso, compará-lo com outros. Trata-se de um processo de descoberta.
Dois exemplos de documentação (criados por mim) que abordam a avaliação de forma mais ou menos explícita são What is Databricks? e a Splunk Observability Cloud Service Description. Ambos apresentam os principais pontos fortes e o posicionamento do produto, juntamente com informações que ajudam os potenciais clientes a decidir se devem avançar.
Esta dimensão de venda discreta é frequentemente negligenciada pelas frameworks de documentação, deixando que o SEO e o marketing conduzam a documentação para algo que já não é documentação. Quando a documentação é produzida com a avaliação em mente, torna-se mais fácil manter o marketing sob controlo e abre-se também a possibilidade de utilizar métricas de conversão.
O que o utilizador quer fazer
Os utilizadores da documentação são também potenciais clientes ou avaliadores. Quem lê deve conseguir discernir as principais qualidades do produto e compará-lo com outros. Trata-se de um processo de descoberta.
Sinais de que a documentação não responde a esta necessidade
- As equipas de apoio e vendas respondem repetidamente às mesmas perguntas: «O que é isto?»
- Os potenciais clientes descobrem o que o produto faz no material de marketing, não na documentação.
- Não existe uma página que apresente o posicionamento ou os principais pontos fortes do produto.
Dois exemplos reais
Tipos de conteúdo comuns
| DITA | Diátaxis | Good Docs Project |
|---|---|---|
| <topic>, <concept> | Sem equivalente direto (o mais próximo é Explicação) | Visão geral, Página de destino |
Uma métrica
conversão · Taxa de conversão da documentação para a adoção do produto.