Como gerenciar a documentação do usuário final para um projeto sob integração contínua? [fechado

Question

Eu tenho um projeto sob integração contínua e gostaria de adicionar a documentação do usuário final ao projeto. A documentação do usuário final é um manual do usuário, não a documentação da API. Em nosso ambiente, usamos Windows, C#, MSBuild, CruiseControl.net e Subversão. Atualmente, estamos usando o DoctoHelp para criar nosso arquivo de ajuda, que é baseado em um documento do MSWORD.

Estou procurando algumas orientações sobre como gerenciar a documentação do usuário final. Quais ferramentas de documentação devo usar? Alguma das ferramentas de documentação deve fazer parte do script de construção? Os arquivos de saída da ferramenta de documentação devem ser armazenados na subversão? Que tipo de arquivos de ajuda seria melhor usar?

Answer 1

Nós estamos usando XMLMind XML Editor Para produzir a documentação do usuário no formato DocBook unificado que pode ser armazenado em um sistema de controle de versão nos últimos 6 anos. Usamos transformações XSL padrão para gerar usuário Documentação do DocBook no formato HTML e PDF. Obviamente, tudo isso faz parte do ciclo contínuo de integração e liberação.

Espero que isto ajude.

Answer 2

Não conheço doctohelp, mas aqui está minha opinião:

Mesmo que seja a única coisa que você faz: comece a adicionar seu arquivo de ajuda gerado e todos os arquivos que você usou para criá -lo no seu sistema de controle de versão.

Se a geração do arquivo de ajuda não for muito mais do que o processamento de um arquivo do Word Doc, talvez eu não se desse ao trabalho de integrá -lo no servidor CI. A pasta de artefato de compilação do seu servidor de CI conterá o arquivo de ajuda, conforme buscado no controle da versão.

Se houver um monte de arquivos (talvez imagens externamente vinculadas no documento?) E há uma chance de falha, você poderá adicioná -lo (se a ferramenta de criação de arquivos de ajuda permitir).

Basicamente, o que seu servidor de CI provaria então é se ele pode reproduzir seu arquivo de ajuda do controle da versão (você se comprometeu e adicionou tudo?). Levando -o ainda mais, você pode criar testes automatizados que examinariam o arquivo de ajuda e a comparar com os IDs HelpContext referenciados no próprio software. Mas aqui estou especulando (não fiz arquivos de ajuda há anos :-)).

Answer 3

Você pode querer dar uma olhada no Doxygen:http://www.doxygen.nl/

Doxygen é um sistema de documentação para C ++, C, Java, Objective-C, Python, IDL (Flavoros Corba e Microsoft), Fortran, VHDL, PHP, C#