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?
Respostas:
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.
fonte
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
fonte
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.)
fonte
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.
fonte
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.
fonte
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.
Manutenção
O local onde a fonte desta documentação dependerá do público e de quem está escrevendo para o público.
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.
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.
fonte
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.
fonte
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).
fonte