O triângulo: produto, código, documentação
Uma ferramenta útil resolve uma dor específica para uma pessoa concreta (nem que sejas tu daqui a 6 meses). A documentação não é marketing: é o contrato de uso: o que faz, o que não faz, como instalar, como reportar bugs.
Antes de escreveres uma linha de UI
- Job story: "Quando [situação], quero [motivação], para [resultado]."
- Happy path + 2 edge cases: anota inputs estranhos, erres de rede, permissões.
- Definition of Done: o que tem de estar verdade para dizeres "versão 0.1"?
README que alguém lê até ao fim
Estrutura sugerida
- 1 frase: o que é e para quem.
- Demo ou screenshot: prova visual imediata.
- Instalação / Quick start: comandos copy-paste que funcionam num ambiente limpo.
- Configuração: variáveis de ambiente numa tabela (nome, obrigatória?, exemplo).
- Limitações conhecidas: gera confiança; esconder bugs mata a adopção.
- Contribuir / Licença: mesmo que seja só tu, deixa a porta aberta.
🧪Experimenta isto
Cola o teu README numa IA e pede: "Actua como developer nova no projecto. O que fica confuso ou perigoso? Sugere reordenação e uma secção FAQ de 5 perguntas."
Documentação "viva" no código
Para APIs internas, prefere exemplos executáveis (snippets testados) a parágrafos longos. Para UI, screenshots ou GIFs curtos no PR já valem mais do que outro ficheiro markdown esquecido.
💡Dica
Mantém um CHANGELOG.md simples (Added / Fixed / Breaking): mesmo em projectos pessoais. O teu "eu futuro" agradece.
Prompts úteis para gerar docs com IA
Especificação de funcionalidade
Contexto: [descreve a ferramenta em 3 frases] Audiência: [iniciante em X / power user] Tarefa: gera uma secção "Como usar" com passos numerados, avisos de segurança, e uma tabela de erros comuns com causa provável e solução.
Release notes
A partir deste diff ou lista de commits: [cola aqui] Gera release notes em tom humano, bullets curtos, e uma secção BREAKING se aplicável.
Manutenção sem drama
1
Issues mínimas
Template curto: contexto, passos para reproduzir, comportamento esperado vs actual.
2
Versões semânticas leves
0.x até teres API estável; depois 1.0.0 quando prometeres menos breaking changes.
3
Deprecações com data
Se removes algo, diz o que usar em alternativa e até quando o antigo funciona.
No ecossistema Descomplicai
O repositório tem dezenas de mini-ferramentas em (tools). Usa-as como referência de padrões: layout consistente, mensagens de erro claras, e um README por pasta quando a ferramenta crescer além do óbvio.