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

Fechado . Esta questão é baseada em opiniões . No momento, não está aceitando respostas.

Deseja melhorar esta pergunta? Atualize a pergunta para que ela possa ser respondida com fatos e citações editando esta postagem .

Fechado há 6 anos .

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

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.

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