quel type de système de documentation technique en ligne recommanderiez-vous? [fermé]

11

l'objectif est d'avoir un système de documentation en ligne, avec ces exigences majeures:

  • sera principalement utilisé comme une étape intermédiaire pour la documentation technique finale de toute notre application (qui ne sera probablement jamais terminée cependant:]). Il serait généralement utilisé comme suit: quelqu'un a un problème, je le corrige et j'écris le correctif immédiatement. Ce qui se passe maintenant devient ingérable: quelqu'un a un problème, je le corrige, moi et quelqu'un sommes heureux mais 2 mois plus tard, quelqu'un d'autre a le même problème et personne ne se souvient de ce qu'était le correctif.
  • accessible de partout, derrière notre serveur apache
  • gestion des utilisateurs / groupes, permettant un accès en lecture seule / lecture-écriture / administrateur
  • le format n'est pas trop important: le texte brut ferait l'affaire, le style wiki serait quand même plus joli
  • pas cher ou gratuit

quelques idées à moi:

  • il suffit de servir des fichiers sur un partage de fichiers ou via ssh (inconvénients: pas trop copmatible avec Windows, avantages: simple, peut être n'importe quel type de fichier)
  • le conserver dans un SCM (svn / git, idem comme ci-dessus mais plus facile d'accès et de contrôle d'accès)
  • Confluence: nous utilisons déjà Jira, est-ce que Confluence en vaut la peine? Comment s'intègre-t-il avec Jira?
  • autre chose?

N'hésitez pas à les commenter ou à partager votre expérience avec d'autres systèmes.

documentation stijn
la source
La documentation est-elle générée à partir de code (tel que Javadocs) ou est-elle écrite à partir de zéro, comme un guide de l'utilisateur, ou une combinaison des deux?
FrustratedWithFormsDesigner
il s'agit principalement d'un guide de l'utilisateur, pas d'une documentation de code (enfin, nous l'avons aussi, généré par doxygen, nous pourrions l'inclure, mais ce n'est pas le premier point d'intérêt)
stijn
Je remettrais de l'argent à Spolsky.
Job

Réponses:

11

J'allais proposer un Wiki

Comme Confluence est un wiki, je pense que l'utiliser avec votre JIRA est une excellente idée. Vous aurez l'avantage de pouvoir relier directement les problèmes JIRA, et donc le code / doc / quel que soit le changement effectué, etc.

La clé de tout dépôt de doc de code comme celui-ci est l'aspect navigation. Vous ne voulez pas de pages déconnectées, difficiles à trouver, etc. Réfléchissez à une «mise en page de site» comme vous le feriez pour un site Web.

Martijn Verburg
la source
Confluence peut apparemment exporter dans différents formats plats. Cela ressemble à l'un des moyens les plus faciles de passer d'une production facilement modifiable à une production terminée
2
Nous avons Confluence où je travaille - nous avons migré de MediaWiki - et il fait un bon travail de sortie vers un certain nombre de formats (Word étant le plus populaire). Mais sachez que ses outils d'édition WYSIWYG sont incroyablement bogués et que le système de marquage laisse beaucoup à désirer, au moins lors de notre installation.
Philip Regan
+1 pour Wiki, j'ai également trouvé Trac très utile dans ce cas car il s'intègre avec SVN permettant également le partage de fichiers.
nous avons vérifié un essai Confluence, et ça va être la solution. Semble être en mesure de faire bien plus que ce dont nous avons besoin, mais c'est assez facile de travailler avec. J'ai essayé Trac il y a quelques années et c'était un peu trop compliqué à mon goût, surtout en ce qui concerne les plugins, etc.
stijn