Eu sou o criador de um crescente projeto de código aberto. Atualmente, estou ficando frustrado, tentando descobrir a melhor maneira de gerenciar a documentação. Aqui estão as opções que eu considerei:
- Site HTML
- Uma Wiki do Github
- Arquivos Markdown hospedados no Github
- Colocando todos os documentos no Github README.md
A documentação já está escrita no Markdown, simplesmente não consigo descobrir como quero disponibilizá-la. Estou realmente interessado no Git, pois posso ramificar e marcar a documentação da mesma forma que posso ramificar e marcar a fonte.
Eu poderia usar uma biblioteca Markdown para traduzir o Markdown para HTML e exibi-lo em um site com estilo. Eu precisaria fazer o upload de alterações no site sempre que houvesse uma alteração e seria difícil gerenciar todas as diferentes "tags" da documentação.
Os Wikis do Github (tanto quanto eu sei) não mudam de acordo com o ramo em que você está. Portanto, eu só podia ter a versão "mestre" da documentação no formulário do Github Wiki a qualquer momento.
Colocar tudo isso no README do Github é bem legal. Recebo ramificações e tags, mas é um pouco cansativo de usar e não se presta bem à navegação fácil.
Estou perdendo alguma solução incrível? Que outras opções eu tenho?
fonte
Respostas:
Uma coisa que eu diria é que a documentação DEVE estar nos arquivos de código-fonte (usando a marcação que você desejar) e, em seguida, os documentos gerados automaticamente a partir deles.
Pelo menos no seu site, você pode gerar downloads formatados dos documentos como parte do pacote de origem, para que o usuário não precise de uma ferramenta de documento específica
A chance de alguém consertar / adicionar uma função e depois editar / adicionar um pouco de documentação de marcação imediatamente adjacente no mesmo arquivo pode ser baixa, mas a chance de encontrar um arquivo completamente diferente em um repositório de documentos diferente para fazer o mesmo é um pouco pequena. menos que zero.
Você sempre pode ter um tutorial.h que contém grandes blocos de texto, se desejar - mas trate-o como parte da fonte
fonte
Se o seu projeto for uma biblioteca, nada será melhor que a documentação no estilo javadoc para documentar a sintaxe da API dos comentários no próprio código.
Quanto à documentação sobre tutoriais, exemplos de uso etc. Eu recomendo o uso de um formato wiki. Outros projetos que vi têm páginas separadas para diferentes ramos. Ao iniciar um novo ramo, basta copiar o que não foi alterado para uma nova página e atualizar a partir daí.
Meu motivo para recomendar um wiki é anedótico, mas por experiência pessoal. Contribui com atualizações de documentação para projetos de código aberto em várias ocasiões, mas todos eles já apareceram em wikis. Se estou tentando descobrir alguma coisa e a documentação é enganosa ou inútil, depois que descobrir, atualizarei o wiki enquanto estiver nos documentos e ele estiver fresco em minha mente. Se não for por uma sensação de retribuição, pelo menos porque sei que provavelmente precisarei procurar novamente daqui a um ano ou dois.
Se não houver um wiki, a barreira à entrada é muito alta para incomodar, entre descobrir como a documentação é gerada, onde é armazenada, obter as últimas informações sobre o controle de origem, como fazer edições, fazer as edições reais e navegando nas listas de discussão para obter um patch aceito.
Se você deseja um controle rígido sobre sua documentação, use o que for mais confortável para você, porque você será o único a atualizá-la. Se você deseja incentivar a participação da comunidade, use um wiki.
fonte
Arquivos Markdown hospedados com a fonte funcionam extremamente bem.
Os baseados em RST docutils ferramentas, por exemplo, pode criar HTML ou látex (e PDFs) de um conjunto de documentos.
Isso - com efeito - combina suas opções 1 e 3.
fonte
Se você não se importa de converter os documentos de Markdown em reStructuredText, considere o Sphinx . É tão fácil quanto a redução, mas é muito mais poderoso.
fonte