A maioria dos tickets de suporte de produtos de código-fonte não são bugs. São problemas de instalação, dúvidas de configuração e pedidos do tipo "como eu mudo X" que algumas páginas bem posicionadas teriam respondido. Uma boa documentação de software para clientes é organizada em torno dessas perguntas: o que o comprador precisa para instalar o app, configurá-lo, usá-lo, personalizá-lo, atualizá-lo e corrigi-lo quando algo dá errado.
A documentação também influencia se as pessoas compram ou não. Ela é um dos sinais de confiança descritos no nosso guia sobre como vender o código-fonte do seu web app ou SaaS, e os revisores da AppTrovo verificam se há instruções claras de instalação e uso antes de um produto ser publicado. Este guia mostra o que escrever, em que ordem e como mantê-lo correto quase sem esforço extra.
O objetivo não é ter mais páginas. É ter menos tickets por venda, que é o que torna uma licença única lucrativa ao longo do tempo.
De quais documentos um produto de código precisa?
Os compradores de código-fonte chegam com objetivos diferentes em momentos diferentes. Separe sua documentação por objetivo para que cada leitor encontre a resposta rapidamente. O framework Diátaxis é um modelo conhecido para essa divisão entre tutoriais, guias práticos, referência e explicação. Para um web app vendável, seis documentos cobrem quase tudo:
| Documento | Pergunta do leitor | Evita tickets como |
|---|---|---|
| README / Início rápido | O que é isto e como faço para colocá-lo em funcionamento? | "Por onde eu começo?", "Qual arquivo eu envio?" |
| Guia de instalação | Como instalo no meu servidor, passo a passo? | "Página em branco depois do upload", "Erro de conexão com o banco de dados" |
| Referência de configuração | O que cada configuração e variável de ambiente faz? | "Os e-mails não estão sendo enviados", "Como mudo a moeda?" |
| Guia do usuário | Como realizo uma tarefa no app? | "Como adiciono um membro da equipe?", "Onde ficam os relatórios?" |
| Guia de personalização | Como altero o código com segurança? | "Como mudo o logotipo?", "Como adiciono um campo?" |
| Solução de problemas e notas de atualização | Algo quebrou ou quero a nova versão | "Erro 500 depois da atualização", "Os jobs da fila não estão rodando" |
Inclua a documentação no download (uma pasta docs/ ou um arquivo HTML) e publique o mesmo conteúdo online. Compradores que pesquisam uma mensagem de erro encontrarão uma página pública; compradores em um servidor sem acesso à internet ainda poderão ler a cópia local.
Comece com um README escrito para compradores
O README do seu repositório provavelmente foi escrito para você mesmo. O README de um comprador responde a perguntas diferentes logo na primeira tela:
- O que é isto, em uma frase.
- Requisitos: versão da linguagem, extensões, banco de dados, cron, fila e quaisquer serviços pagos de terceiros.
- O que há no ZIP: qual pasta enviar, qual é a documentação e qual é opcional (arquivos de design, dados de exemplo).
- O caminho mais rápido até um app funcionando: de cinco a dez linhas, com link para o guia de instalação completo.
- Logins padrão criados pelo instalador, com um lembrete para alterá-los.
- Onde obter ajuda: link da documentação, como abrir um ticket de suporte e o que incluir nele.
- Versão e link para o changelog.
Modelo de guia de instalação
O guia de instalação evita mais tickets do que todo o resto junto. Escreva-o instalando seu produto em um servidor limpo enquanto faz anotações, nunca de memória. Use esta estrutura:
- Antes de começar. Uma checklist que o comprador possa marcar: acesso ao servidor, versão do PHP ou do runtime, extensões necessárias, um banco de dados e um usuário com privilégios totais sobre ele, um domínio apontando para o servidor, certificado SSL e a possibilidade de configurar um cron job.
- Envie os arquivos. Diga exatamente qual pasta vai para onde e qual pasta deve ser a raiz web (para um app Laravel,
public/). Inclua uma observação para hospedagem compartilhada caso a raiz web não possa ser alterada. - Instale as dependências caso não estejam incluídas, com os comandos exatos, como
composer install --no-dev --optimize-autoloader. - Crie o arquivo de ambiente. Copie
.env.examplepara.enve liste os valores que precisam ser alterados. - Defina as permissões de arquivos. Indique os diretórios que precisam ter permissão de escrita, por exemplo
storage/ebootstrap/cache/, e explique o porquê em vez de recomendar 777. - Execute o instalador ou as migrations. Mostre o que cada tela do instalador pede, incluindo a etapa da chave de licença.
- Configure tarefas agendadas e filas. Forneça a linha exata do cron e como executar ou supervisionar os workers da fila.
- Primeiro login e primeiras tarefas. Credenciais padrão, as três primeiras configurações a alterar e como enviar um e-mail de teste.
- Verifique a instalação. Uma lista curta de coisas que agora devem funcionar, como "o painel carrega", "um e-mail de teste chega", "a tarefa agendada aparece no log".
- Se algo deu errado: links para os cinco erros de instalação mais comuns na sua página de solução de problemas.
Adicione uma seção curta e separada para cada configuração de hospedagem comum que você suporta: um VPS com Nginx, um VPS com Apache, hospedagem compartilhada com cPanel, Docker. Se você não suporta alguma, diga isso. Os compradores também podem aprender o processo geral em guias como como instalar um web app Laravel em um VPS, mas o seu guia ainda precisa cobrir as etapas específicas do seu produto.
Escreva uma referência de configuração, não apenas comentários no .env
Comentários no .env.example ajudam desenvolvedores, mas muitos compradores são donos de negócios ou desenvolvedores juniores. Uma tabela de referência responde "o que isto faz e quando devo alterar?" em um só lugar.
| Variável | Padrão | O que faz | Quando alterar |
|---|---|---|---|
APP_URL | http://localhost | URL base usada em links e e-mails | Sempre; defina com seu domínio real usando https |
MAIL_MAILER | log | Como os e-mails são enviados | Defina como smtp ou seu provedor antes de entrar em produção |
QUEUE_CONNECTION | sync | Se os jobs em segundo plano rodam imediatamente ou em um worker | Use database ou redis em sites movimentados e execute um worker |
APP_TIMEZONE | UTC | Fuso horário para datas e tarefas agendadas | Defina com o fuso horário da sua empresa |
A tabela acima é um exemplo; documente todas as variáveis que o seu produto lê. Faça o mesmo com as telas de configuração dentro do app: o que cada configuração altera e qual é o padrão seguro.
Solução de problemas: escreva entradas em torno de mensagens de erro reais
Os compradores pesquisam o texto exato que veem. Uma página de solução de problemas que usa essas strings exatas como títulos é encontrada pelos mecanismos de busca e pela própria busca do site do comprador. Use este formato em cada entrada:
Erro:
SQLSTATE[HY000] [2002] Connection refusedO que significa: o app não consegue alcançar o servidor de banco de dados.
Causas comuns:
DB_HOSTouDB_PORTincorretos; o serviço de banco de dados não está em execução; o host só aceita conexões de localhost.Como corrigir: confira os valores no
.env, confirme que o banco de dados está rodando, tente127.0.0.1em vez delocalhoste depois limpe o cache de configuração.
Comece pelos erros que você já conhece: uma página em branco com o debug desativado, o erro 500 depois do upload, erros de permissão no storage, a extensão PHP ausente, falhas de autenticação de e-mail, cron que não roda e falhas na verificação de licença. Depois, adicione uma nova entrada sempre que um ticket revelar um novo erro.
Guia de personalização: responda "como eu mudo X"
Pedidos de personalização são a segunda maior fonte de tickets, e muitos vendedores os respondem um a um para sempre. Documente de uma vez as dez alterações mais comuns:
- Alterar o logotipo, as cores e o nome do app.
- Editar modelos de e-mail e textos de notificação.
- Adicionar ou editar um idioma ou uma string de tradução.
- Adicionar um campo a um formulário e ao banco de dados.
- Adicionar um item de menu ou uma página.
- Alterar a moeda, o formato de data e o formato de número.
- Conectar outro provedor de pagamento, SMS ou e-mail.
- Adicionar uma função ou permissão.
Para cada uma, mostre onde fica o arquivo, o que alterar e como manter a alteração nas atualizações futuras. Esse último ponto é importante: se os compradores editarem arquivos centrais, cada atualização vira um ticket de suporte. Em vez disso, oriente-os para pontos de extensão, pastas de override ou configuração. Nosso guia sobre suporte, atualizações e versionamento explica como planejar as versões para que instalações personalizadas possam ser atualizadas.
Transforme tickets em documentação todo mês
A documentação fica desatualizada e nunca cobre tudo na primeira tentativa. Um ciclo mensal simples a mantém útil:
- Marque cada ticket com uma categoria: instalação, configuração, uso, personalização, bug, pré-venda, outro.
- Uma vez por mês, conte as marcações. Escolha as três perguntas mais frequentes que não sejam bugs.
- Escreva ou melhore a página que teria respondido cada uma, usando as próprias palavras do comprador no título.
- Responda a tickets futuros com um link e um resumo de uma linha. Se o link não resolver, a página precisa de ajustes.
- Corrija o produto quando a mesma confusão continuar voltando. Uma mensagem de erro mais clara ou uma verificação no instalador é melhor do que qualquer documento.
Como exemplo ilustrativo, um vendedor que recebe 40 tickets por mês e descobre que 15 são sobre configuração de e-mail normalmente consegue eliminar a maioria deles com uma boa página e uma etapa no instalador que envia um e-mail de teste.
Faça o produto documentar a si mesmo
A melhor documentação é aquela que o comprador nunca precisa abrir:
- Verificações no instalador que testam a versão do PHP, as extensões, as pastas com permissão de escrita e a conexão com o banco de dados, e explicam as falhas em linguagem simples.
- Mensagens de erro úteis que dizem o que fazer em seguida ("O servidor de e-mail rejeitou o login. Verifique MAIL_USERNAME e MAIL_PASSWORD em Configurações").
- Uma página de status do sistema na área administrativa mostrando versões, status da fila, última execução do cron e permissões do storage. Os compradores podem tirar uma captura de tela dela ao abrir um ticket.
- Textos de ajuda inline ao lado das configurações fáceis de entender errado.
- Estados vazios que explicam a próxima ação ("Nenhum membro da equipe ainda. Adicione o primeiro membro da equipe").
Regras de estilo que tornam a documentação mais fácil de seguir
- Escreva passos numerados para tudo o que é feito em sequência, uma ação por passo.
- Mostre comandos e caminhos exatos e diga onde executá-los.
- Informe o resultado esperado após as etapas importantes, para que os leitores saibam quando algo deu errado.
- Use capturas de tela para as telas de configuração e atualize-as quando a interface mudar.
- Escreva em inglês americano simples, com frases curtas; muitos compradores leem por meio de uma ferramenta de tradução.
- Versione a documentação. Marque as seções que se aplicam apenas a certas versões e mantenha notas de atualização para cada versão lançada.
Os princípios de documentação do Write the Docs, gratuitos, são uma boa checklist de clareza e estrutura.
Checklist de documentação antes de enviar
- O README responde o que é, os requisitos, o que há no ZIP, o início rápido, os logins padrão e onde obter ajuda.
- Guia de instalação testado em um servidor limpo, com uma seção para cada configuração de hospedagem suportada.
- A referência de configuração cobre todas as variáveis de ambiente e configurações importantes.
- O guia do usuário cobre as principais tarefas de cada função.
- O guia de personalização cobre as dez alterações mais comuns e como mantê-las nas atualizações.
- A página de solução de problemas usa as mensagens de erro exatas como títulos.
- O changelog e as notas de atualização estão incluídos.
- A documentação está no download e online.
Antes de enviar, compare com a checklist de envio de produtos e os padrões de código da AppTrovo. Quando sua documentação estiver pronta, seu anúncio pode criar um link para ela na seção de requisitos, o que também ajuda os compradores na pré-venda.
Perguntas frequentes
O que a documentação de software voltada ao cliente deve incluir?
No mínimo: um README, um guia de instalação, uma referência de configuração, um guia do usuário, um guia de personalização e uma página de solução de problemas com notas de atualização. Cada documento responde a uma pergunta diferente, então mantenha-os separados e crie links entre eles.
A documentação deve ficar dentro do ZIP ou online?
Ambos. A cópia no ZIP sempre corresponde à versão que o comprador tem. A cópia online pode ser pesquisada, é fácil de linkar nas respostas de suporte e pode ser atualizada entre uma versão e outra. Deixe claro a qual versão cada página online se aplica.
Quão detalhado deve ser um guia de instalação?
Detalhado o suficiente para que alguém que já instalou um web app antes, mas nunca o seu, consiga concluir sem entrar em contato com você. Inclua comandos exatos, caminhos, permissões necessárias e o resultado esperado após cada etapa importante. Teste-o em um servidor limpo a cada versão que altere os requisitos.
Como sei qual documentação escrever primeiro?
Analise seus tickets de suporte e as perguntas de pré-venda. Instalação e configuração geralmente vêm primeiro, seguidas pelos pedidos de personalização mais comuns. Se você ainda não tem tickets, instale o produto você mesmo em um servidor limpo e documente cada ponto em que precisou parar para pensar.
Uma boa documentação realmente reduz reembolsos?
Instalações malsucedidas e expectativas não atendidas são motivos comuns para os compradores pedirem reembolso, e requisitos claros, junto com um guia de instalação testado, resolvem ambos. Os reembolsos na AppTrovo seguem a política de reembolso, mas evitar o problema é sempre mais barato do que lidar com o pedido.