que tipo de sistema de documentação técnica online você recomendaria? [fechadas]

11

o objetivo é ter um sistema de documentação on-line, com os seguintes requisitos principais:

  • será usado principalmente como um estágio intermediário para os documentos técnicos finais de todos os nossos aplicativos (que provavelmente nunca serão concluídos:]). Normalmente, seria usado da seguinte maneira: alguém tem um problema, eu o corrigo e anote a correção imediatamente. O que acontece agora está ficando incontrolável: alguém tem um problema, eu conserto, eu e alguém estamos felizes, mas 2 meses depois alguém mais tem o mesmo problema e ninguém se lembra qual foi o problema.
  • acessível de qualquer lugar, rodando atrás do nosso servidor apache
  • gerenciamento de usuário / grupo, permitindo acesso somente leitura / leitura / gravação / administrador
  • o formato não é muito importante: texto simples, o estilo wiki seria melhor
  • barato ou livre

algumas idéias minhas:

  • basta servir arquivos em um compartilhamento de arquivos ou através do ssh (contras: não muito compatível com o Windows, profissionais: simples, pode ser de qualquer tipo de arquivo)
  • mantenha-o em um SCM (svn / git, idem como acima, mas mais fácil de acessar e controlar o acesso)
  • Confluence: já usamos Jira, vale a pena? Como ele se integra ao Jira?
  • algo mais?

Por favor, não hesite em comentar sobre isso ou compartilhar sua experiência com outros sistemas.

documentation stijn
fonte
A documentação está sendo gerada a partir do código (como Javadocs) ou está sendo escrita do zero, como um guia do usuário ou alguma combinação dos dois?
FrustratedWithFormsDesigner
é principalmente mais de um guia do usuário, não documentação de código (bem, temos que tão bem, gerado pelo doxygen, podemos incluí-lo, mas não é o primeiro ponto de interesse)
Stijn
Eu entregaria algum dinheiro para Spolsky.
Job

Respostas:

11

Eu ia sugerir um wiki

Como Confluence é um wiki, acho que usá-lo com o seu JIRA é uma excelente ideia. Você terá a vantagem de poder se vincular diretamente aos problemas do JIRA e, portanto, o código / doc / qualquer alteração feita etc.

A chave para qualquer repositório de documentos de código como esse é o aspecto da navegação. Você não deseja páginas desconectadas, difíceis de encontrar, etc. Pense em um "layout do site", como faria em um site.

Martijn Verburg
fonte
Aparentemente, a confluência pode exportar em vários formatos planos. Soa como uma das maneiras mais fáceis de passar de uma edição fácil para uma produção finalizada.
2
Temos o Confluence onde trabalho - migramos do MediaWiki - e ele faz um bom trabalho gerando vários formatos (o Word é o mais popular). Mas lembre-se de que suas ferramentas de edição WYSIWYG são incrivelmente defeituosas e o sistema de marcação deixa muito a desejar, pelo menos em nossa instalação.
Philip Regan
+1 no Wiki, também achei o Trac muito útil nesse caso, pois ele se integra ao SVN, permitindo o compartilhamento de arquivos.
verificamos um teste do Confluence e essa será a solução. Parece ser capaz de fazer muito mais do que precisamos, mas é muito fácil trabalhar com isso. Tentei Trac um par de anos atrás e foi um pouco confuso para o meu gosto, especialmente quando se tratava de plugins etc
Stijn