Quelle est la meilleure façon de stocker la documentation du logiciel? [fermé]

Question

Une réponse évidente est "un wiki interne". Quels sont les avantages et les inconvénients d'un wiki utilisé pour la documentation de logiciels? D'autres suggestions? Qu'utilisez-vous pour la documentation de votre logiciel?

Loren Segal - Malheureusement, aucun outil de documentation ne permet de compiler des informations à partir du code source. commentaires, mais je conviens que ce serait le meilleur moyen de stocker la documentation technique. Ma question concernait tous les types de documentation, du type sysadmin à la documentation utilisateur.

Answer 1

C'est une question très ouverte et dépend de nombreux facteurs.

En règle générale, si vous utilisez un langage disposant de bons outils de génération de documentation (javadoc, doxygen, C # de MS), vous devez écrire votre documentation au-dessus de vos méthodes et laisser vos outils générer les pages. L’avantage est que vous conservez la source de votre texte à côté de votre code, ce qui signifie qu’il est orgnanisé à l’endroit logiquement correct et facilement modifiable lorsque vous modifiez le comportement de la méthode.

Si vous ne disposez pas d'un bon support pour les outils de documentation ou n'avez pas accès au code source, les wiki ne sont pas une mauvaise idée, mais ils constituent un second choix après ce qui précède.

Remarque: je ne parle que de la documentation de code ici. Il est évident que d'autres artefacts ne peuvent pas être stockés avec du code - un wiki est un excellent endroit pour mettre ces documents. Alternativement, si vous utilisez un CMS, vous pouvez simplement le valider dans un dossier docs / sous la forme text / pdf / quels que soient les fichiers à modifier via le référentiel. L'avantage est qu'ils restent dans le référentiel s'il est déplacé alors qu'un wiki ne le fait pas (nécessairement).

Answer 2

Les outils sont importants, mais ne vous perdez pas à chercher l’outil magique. Aucun outil que j'ai trouvé n'a encore de "documenter tout magiquement en utilisant de minuscules elfes invisibles". case. : -)

Un wiki fonctionnera bien. Ou Sharepoint. Ou Google Docs. Ou vous pouvez utiliser un référentiel SVN. Enfer, vous pourriez le faire avec des stylos, du papier à lettres et des classeurs si vous en aviez vraiment besoin. (Je ne recommande vraiment pas ça!)

L'important, c'est que vous deviez vous associer à l'ensemble de l'organisation. Ce qui se passe dans beaucoup de magasins, c’est qu’ils vont dépenser beaucoup de temps et d’argent pour une solution sophistiquée telle que Sharepoint, puis que tout le monde l’utilise religieusement pendant environ deux semaines, puis que les gens s’efforcent de franchir la dernière quiconque en entend parler.

En fonction de votre organisation, de votre domaine d'activité, du type de produits que vous développez, etc., il existe plusieurs solutions, mais vous devez, d'une manière ou d'une autre, configurer un système et le l'utiliser . . Nommez le tsar de la documentation officielle, donnez-leur un indice, et dites-leur de frapper les gens à la tête chaque fois qu'ils se disent "ah ouais, je vais finir de documenter ça la semaine prochaine ...". si c'est ce que ça prend. : -)

En ce qui concerne les outils ... Je recommanderais Confluence par Atlassian. C'est un excellent wiki, il est conçu pour fonctionner dans un environnement d'entreprise, il possède de nombreuses fonctionnalités astucieuses, il est personnalisable, il s'intègre bien avec certains des autres outils astucieux d'Atlassian et constitue en gros un produit assez solide.

Answer 3

& # 171; Documentation du logiciel & # 187; est un terme très général. Il existe une & # 171; Documentation pour l'utilisateur final & # 187 ;, & # 171; Documentation pour les développeurs & # 187 ;, & # 171; Documentation QA & # 187 ;. Le premier est généralement développé par des techniciens qualifiés. D'autres peuvent être formés dynamiquement à partir de wikis, de commentaires de documentation à partir de code source, etc. Tout ce processus de maintenance est généralement très complexe et chaque éditeur de logiciel suit son propre chemin. Mais il y a un point nécessaire pour toutes ces manières: chaque auteur de code, architecte, gestionnaire, ingénieur en chef DOIT stocker correctement chaque information qui peut être utile aux autres. Et quelqu'un d'autre DOIT garder un œil sur ce stockage de pièces et réorganiser les pièces si nécessaire. Toutes ces étapes grandement améliorent toutes les activités liées au processus de développement.

Answer 4

En supposant que vous parlez de documentation sur le code par rapport à la documentation utilisateur, un wiki interne est tout indiqué si vous n'avez pas besoin de distribuer la documentation du code en dehors de votre organisation, à des sous-traitants ou à des partenaires.

Javadoc ou DOxygen est plus approprié si vous souhaitez une documentation de code distribuable.

Si vous vous référez à la documentation utilisateur, vous pouvez consulter DITA . .

Answer 5

J'ai commencé à expérimenter un moyen de faire de la documentation utilisateur avec ces objectifs:

Documents relativement liés Markdown / Html / Javascript / basés sur des fichiers pour la portabilité ( peut s'exécuter sur un système de fichiers local ou vous pouvez le lancer sur un serveur Web ), construit lors du traitement des captures d'écran ( redimensionner de manière interactive ), et de l'open source au cas où quelqu'un d'autre voudrait faire quelque chose avec cette chose folle.

Votre source de document est écrite en Markdown et rendue au format HTML via Javascript au moment de l'exécution du navigateur.

  

Mandown & nbsp; - & nbsp; http://wittman.org/mandown/

Answer 6

Nous utilisons actuellement une documentation en ligne analysée par une application externe (PHP + PhpDocumenter) ainsi que divers wikis internes. Parfois, au mieux, c'est douloureux (principalement parce qu'une seule personne met à jour les wikis ou les documents ...)

Cependant, je réfléchissais à utiliser ikiwiki pour les documents internes. Il s'intègre à votre système source (y compris Git, Subversion, Mercurial, Bazaar, TLA et Monotone) pour que tous vos documents soient suivis avec votre projet. Il est construit en Perl et possède un système de plug-in complet (y compris plusieurs langages de balisage, le défaut étant Markdown). De plus, le système de contrôle des sources est basé sur des plugins. Par conséquent, si ce que vous utilisez n'est pas immédiatement pris en charge, vous pouvez ajouter le vôtre. Dans votre langue préférée, si besoin est, car il supporte aussi les plugins non-perl.

Answer 7

Mon entreprise utilise une variété de SharePoint et un wiki. Sharepoint pour des documents spécifiques tels que les exigences, les présentations, les contrats, etc., tandis que le wiki sert de guide d’aide au référentiel de développement pour les tutoriels sur l’utilisation de bibliothèques développées en interne.

Answer 8

Oui, nous utilisons un wiki, nous utilisons également des documents Google. Je trouve que les documents Google sont meilleurs que la plupart des wikis que j'ai essayés et, si vous n'avez pas besoin de suivre tous les changements, vous ne perdez rien. Google Documents fournit un bon cadre de collaboration.