Comment gérer la documentation de l'utilisateur final pour un projet en intégration continue?

Question

J'ai un projet en intégration continue et j'aimerais ajouter une documentation utilisateur au projet. La documentation de l'utilisateur final est un manuel d'utilisation, pas une documentation API. Dans notre environnement, nous utilisons Windows, C#, msbuild, cruisecontrol.net et subversion. Nous utilisons actuellement DocToHelp pour créer notre fichier d'aide, basé sur un document msword.

Je cherche des conseils sur la façon de gérer la documentation de l'utilisateur final. Quels outils de documentation devrais-je utiliser? L'un des outils de documentation devrait-il faire partie du script de construction? Les fichiers de sortie de l'outil de documentation doivent-ils être stockés dans Subversion? Quel type de fichiers d'aide serait le mieux à utiliser?

Answer 1

Nous avons utilisé XMLMind XML Editor pour produire une documentation utilisateur au format docbook unifié pouvant être stockée dans un système de contrôle de version au cours des 6 dernières années. Nous utilisons des transformations XSL standard pour générer l'utilisateur documentation from docbook en format HTML et PDF. Bien sûr, tout cela fait partie du cycle de construction de l'intégration continue et de la libération.

Espérons que cela aide.

Answer 2

Vous pouvez jeter un oeil à Doxygen: http://www.stack.nl/~dimitri/doxygen/

Doxygen est un système de documentation pour C++, C, Java, Objective-C, Python, IDL (Corba et saveurs Microsoft), Fortran, VHDL, PHP, C#

Answer 3

Je ne sais pas DocToHelp mais voici mon:

Même si elle est la seule chose que vous faites: Commencez avec l'ajout de votre fichier d'aide généré et tous les fichiers que vous avez utilisé pour créer dans votre système de contrôle de version.

Si la génération du fichier d'aide n'est pas beaucoup plus que le traitement d'un fichier Word doc alors peut-être que je ne voudrais pas l'intégrer sur le serveur CI. Le dossier d'artefact de construction de votre serveur CI contiendra juste le fichier d'aide récupéré du contrôle de version.

S'il y a un tas de fichiers (peut-être des images externes dans le document?) Et qu'il y a un risque d'échec, vous pouvez l'ajouter (si l'outil de création de fichiers d'aide le permet). Fondamentalement ce que votre serveur CI prouverait alors est s'il peut reproduire votre fichier d'aide du contrôle de version (avez-vous commis et ajoutez tout?). Pour aller encore plus loin, vous pourriez construire des tests automatisés qui examineraient le fichier d'aide à la construction et le compareraient avec les identifiants d'aide contextuelle référencés dans le logiciel lui-même. Mais ici je spécule (je n'ai pas fait de fichier d'aide depuis des lustres :-)).