A documentação do usuário para o seu projeto de software é importante.
Mas, além de demorar para ser escrito, dois pontos principais tornam difícil ter um bom manual:
- Você nunca pode adivinhar todas as sutilezas que seus usuários encontrarão, portanto, ele precisa de atualizações regulares com base no feedback.
- Ele fica fora de sincronia com o código.
Uma maneira de ajudar com o primeiro aspecto é hospedar sua documentação em um wiki .
Desta forma, todos os seus usuários podem contribuir e melhorá-lo, sem a necessidade de acesso ao codebase, nem de um processo formal de aprovação. Qualquer pessoa que descobrir um erro ou simplesmente uma frase enganosa pode corrigi-lo facilmente.
É por isso que todos os projetos do GitHub fornecem um wiki por padrão: eles diminuem o custo de escrita.
Porém, isso tem um custo: aumento do custo de leitura. Para você, atualizar um elemento de API documentado significa primeiro abrir um aplicativo da web e pesquisar todas as páginas que fazem referência a ele. E para seus usuários, já que você precisará adicionar rapidamente indicações de versão ao seu documento para que ele dure.
Reconhecendo isso, muitos projetos incluem a documentação do usuário diretamente como arquivos em seu repositório de código. Isso garante que qualquer estado de documento seja consistente com qualquer versão do código, e faz com que todos os símbolos documentados (chaves de preferência …) apareçam na documentação ao procurá-los na base de código. Isso ajuda a documentação a ficar atualizada, pois um refatorador não pode perdê-la.
Portanto, as opções disponíveis parecem ser usar o poder da multidão e a facilidade de edição para manter seu documento ou integrá-lo adequadamente ao seu código.
No entanto, essas duas opções não precisam ser exclusivas: simplesmente use um wiki e inclua seus dados em sua base de código . Você obtém o melhor dos dois mundos: atualizações fornecidas pelo usuário quando você deseja que sejam incluídas, pesquisa e substituição dentro do código E documentos e controle de versão pelo VCS, tornando os instantâneos de documentos muito fáceis.
E a melhor parte é que isso é extremamente fácil de fazer se você estiver usando Git e GitHub. Como mencionado acima, todos os projetos recebem um wiki. E este wiki é um repositório Git de documentos Markdown.
Assim, você pode simplesmente incluí-lo como um submódulo de seu projeto e ter todos os benefícios listados acima:
git clone git@github.com:USER/PROJECT.git
git submodule add git@github.com:USER/PROJECT.wiki.git doc
git submodule init
git commit -m 'Add docs from GitHub wiki'