Onde colocar a documentação do código?

Atualmente, estou usando dois sistemas para escrever documentação de código (estou usando C ++):

• A documentação sobre métodos e membros da classe é adicionada ao lado do código, usando o formato Doxygen. Em um servidor, o Doxygen é executado nas fontes para que a saída possa ser vista em um navegador da web
• As páginas de visão geral (descrevendo um conjunto de classes, a estrutura do aplicativo, código de exemplo, ...) são adicionadas a um Wiki

Pessoalmente, acho que essa abordagem é fácil porque a documentação sobre membros e classes é muito próxima do código, enquanto as páginas de visão geral são realmente fáceis de editar no Wiki (e também é fácil adicionar imagens, tabelas, ...). Um navegador da web permite que você veja as duas documentações.

Meu colega de trabalho agora sugere colocar tudo no Doxygen, porque podemos criar um grande arquivo de ajuda com tudo (usando o HTML WorkShop da Microsoft ou o Qt Assistant). Minha preocupação é que a edição de documentação no estilo Doxygen seja muito mais difícil (em comparação com o Wiki), especialmente quando você deseja adicionar tabelas, imagens, ... (ou existe uma ferramenta de 'visualização' do Doxygen que não exija que você gere o código antes que você possa ver o resultado?)

O que grandes projetos de código aberto (ou código fechado) usam para escrever sua documentação de código? Eles também dividem isso entre o estilo Doxygen e um Wiki? Ou eles usam outro sistema?

Qual é a maneira mais apropriada de expor a documentação? Por um servidor / navegador da Web ou por um grande arquivo de ajuda (vários 100 MB)?

Qual abordagem você usa ao escrever a documentação do código?

Ter toda a documentação em um sistema em vez de dois pode ser uma vantagem real. Coisas como backup e restauração, controle de versão, pesquisa global, pesquisa e substituição global, reticulação e, como você escreveu, colocando todos os documentos em um documento final, normalmente funcionam com menos "atrito" quando você não precisa manter dois sistemas com capacidade de sobreposição.

Por outro lado, você deve pensar se essas vantagens superam a facilidade do seu Wiki. O círculo editar / gerar / refinar a edição / gerar novamente pode ser mais rápido com o seu Wiki. Eu acho que você pode obter esse ciclo rapidamente, com o doxygen mantendo suas páginas de visão geral como um subprojeto doxygen separado. É possível fazer uso dos recursos de vinculação externa do doxygen, que não substituem uma "visualização rápida", é claro, mas um passo nessa direção. Até o momento, eu não fiz isso sozinho, mas acho que você deve tentar isso sozinho se quiser saber se funciona no seu caso.

Em relação a outros projetos: acho que uma ferramenta como o doxygen é principalmente para documentação da biblioteca. Se você não é um fornecedor de bibliotecas de terceiros e todos os que usam suas bibliotecas têm acesso total ao código-fonte, então a necessidade de uma ferramenta como doxygen é questionável. Em nossa equipe, por exemplo, quase não temos documentos externos fora do código, exceto documentos de usuário final e documentos de nossos modelos de banco de dados. Nossas principais ferramentas para esse tipo de documentação são docbook e fop , o que nos dá resultados satisfatórios.

Use a documentação do código, primeiro. Adicione Wiki e outros métodos, se possível

Eu sei, isso vai ser difícil, mantê-lo.

Resposta prática:

Em termos práticos, a primeira coisa que os desenvolvedores fazem é verificar o código.

Como desenvolvedor, gosto de ter documentação externa, como Wiki (s), manuais. Mas, a primeira coisa que faço é revisar o código (às vezes de outros desenvolvedores, às vezes, o meu).

Como desenvolvedor, que trabalhou em vários projetos e clientes, faço o possível para adicionar documentação externa, mas é comum ter muita carga de trabalho e não ter suporte para um wiki.

Às vezes, os gerentes de projeto e outros chefes não se importam com a documentação, às vezes outros desenvolvedores não.

E, o melhor que posso fazer, é adicionar alguns comentários ao código.

Boa sorte

Alguns usam outros sistemas - dê uma olhada no Sphinx do Python, por exemplo, eles têm um sistema de documentos tudo-em-um que constrói tudo (também funciona para C / C ++)

Eu sempre penso na documentação como separada do código, o doxygen é ótimo, mas é para uma visão geral da API, não para 'documentação'. Por isso, um wiki é ótimo, mas eu prefiro usar o ASCIIDOC e armazenar os resultados no controle de origem junto com o código, principalmente porque eu posso gerar PDFs dele a partir de outras pessoas (por exemplo, testadores, clientes etc.)

O Doxygen permite criar PDF, HTML, páginas wiki, quase tudo o que você pode imaginar.

Minha preferência pessoal é ter Doxygen e wiki e um script ou algo para verificar quando eles divergem.

Desde a versão 1.8.0, o doxygen suporta o Markdown , o que deve tornar a experiência de escrever páginas estáticas igualmente conveniente como em um sistema Wiki.

Público-alvo

Acho que, ao responder a essa pergunta, você realmente precisa perguntar quem deve ler esta documentação. Um desenvolvedor tem necessidades muito diferentes de um usuário ou mesmo de um analista de negócios.

• Como desenvolvedor: documentação associada ao código que está sendo estudado, detalhes como o contrato da interface e exemplos de uso. Talvez alguma documentação de alto nível e especificações de protocolo sejam uma boa medida.
• Como usuário: documentação disponível no menu de ajuda ou em um site acessível sobre como usar o software.
• Como analista de negócios: a documentação disponível como documentos ou como um site acessível é útil. Uma quantidade modesta de detalhes sobre protocolos, arquitetura de alto nível e casos de uso são os melhores.

Manutenção

O local onde a fonte desta documentação dependerá do público e de quem está escrevendo para o público.

• Só tem uma casa de desenvolvedores? Coloque tudo no código. Isso o incentivará a ser atualizado. Você precisará trabalhar em uma cultura que incentive as atualizações de documentação a serem tão importantes quanto as alterações de código.
• Tem uma casa de desenvolvedores e redatores de documentação? Divida as responsabilidades. Use as ferramentas orientadas ao desenvolvedor para desenvolvedores, use as ferramentas dos gravadores de documentação para os gravadores de documentação.

Sempre que possível, garanta que exemplos de código ou casos de uso possam ser executados. Automatize a execução e sinalize falhas internamente. Provavelmente, essas páginas são documentação ruim ou ruim.

Além disso, independentemente das ferramentas nas quais você escolhe escrever sua documentação, você precisa de um meio confiável para associar uma versão específica da documentação a uma versão específica do código. Isso ainda é benéfico, mesmo em terrenos felizes na nuvem, com uma única implantação perene.

Integrando a documentação

Pode ser necessária integração para produzir alguma documentação, mas observe que apenas o usuário espera que um único local acesse toda a documentação necessária.

O analista de negócios está bastante satisfeito com a especificação da API, as especificações de projetos e os cenários de uso, localizados em documentos separados ou em seções separadas de um site.

O desenvolvedor prefere tudo o que é visível a partir da fonte, mas está feliz por ter alguns documentos de design de alto nível e documentos detalhados de especificação de protocolo externos ao código, embora de preferência no mesmo check-out.

Seu caso

Para ser honesto, a documentação em seu wiki provavelmente não é o mesmo tipo de documentação em sua base de código. Pode não fazer sentido mesclar o também.

Por outro lado, integrar os dois pode ser oferecido de algumas maneiras simples.

• As ferramentas de documentação de origem (como doxygen) podem produzir html, e um wiki fica em um servidor da web. Seria um ponto de integração simples servir simplesmente uma versão compilada ao lado do wiki e interligar os dois.
• Alguns produtos wiki permitem que você execute o wiki diretamente de um arquivo que você pode fazer check-in em uma base de código. Isso fornece uma ferramenta wysiwyg simples, mantendo a documentação emparelhada ao código.
• Outros formatos, como o pdf, também podem ser acomodados, mas isso se resumirá às ferramentas específicas que você deseja usar. Pode fazer sentido transformar seu wiki em arquivos de remarcação e alimentá-lo através do doxygen (ou outras ferramentas). Pode fazer sentido pdf o wiki e a fonte separadamente e usar uma ferramenta de fusão de pdf.

No final do dia, descubra qual sistema de documentação tem baixos custos de manutenção e o ajude a fornecer um produto de alta qualidade, visto pelo seu público de desenvolvedores, analistas de negócios e usuários. Qualquer coisa que impeça qualquer um desses grupos reduzirá necessariamente a qualidade dos produtos.

Se você estiver usando ASCII, você deve ocultar seus dados de documentação na parte alta do seu código-fonte! Somente os usuários mais inteligentes (leia-se: merecedores) têm a oportunidade de usar seus documentos.

Ter a documentação em um formato portátil bem definido, facilmente exportável e pode ser a verdadeira vantagem. Se a esfinge morrer (improvável), acabarei convertendo para outro sistema, o que eu acho que seria uma tarefa com script. Mover dados para fora do wiki (presumivelmente armazenado no banco de dados em um formato proprietário pode ser um problema).