Documentation et contrôle des versions

Question

Dans le cadre d'un projet que je suis sur le point de lancer, une documentation sera produite.

Quelle est la meilleure pratique en la matière ?

Les documents doivent-ils être conservés avec le code et les actifs ou doivent-ils faire l'objet d'une documentation distincte ?

Editer

Je voudrais un wiki mais j'aurais besoin d'imprimer les documents etc... Il s'agit d'un projet universitaire.

Answer 1

Cela dépend vraiment de votre équipe. Là où je travaille, nous conservons la documentation dans un wiki qui est relié au site web de notre équipe. Pour les besoins de l'expédition de la documentation, le wiki peut être exporté et nous le soumettons à un analyseur syntaxique qui "affine" l'aspect et la convivialité de la documentation à l'intention des clients.

Stocker la documentation avec le code (typiquement dans votre référentiel de sources) n'est pas une mauvaise idée. Veillez simplement à les séparer. Par exemple, conservez un fichier documents qui se trouve au même niveau que votre src dans votre référentiel. De cette manière, vous pouvez rapidement envoyer la documentation actuelle, vous pouvez facilement suivre les révisions, et toute personne nouvellement impliquée dans le projet peut immédiatement y accéder sans avoir à se rendre à plusieurs endroits pour obtenir des informations.

Answer 2

Le stockage dans le contrôle des sources est une bonne chose.

Answer 3

C'est une question intéressante - fondamentalement, ce que les autres disent est juste en ce qui concerne la documentation générée, les fichiers source et les modèles/etc. devraient être stockés dans le contrôle de source et générés au cours de votre processus de construction.

En ce qui concerne la documentation sur les exigences, les spécifications, etc., j'ai travaillé dans les deux sens et je préfère de loin utiliser SharePoint ou un portail Wiki/documentaire conçu pour le partage et la mise à jour des documents. En effet, la plupart des personnes qui ne sont pas des développeurs ne sont pas à l'aise avec les systèmes de contrôle des sources, et vous ne bénéficiez d'aucun des avantages de la fusion intelligente si vous utilisez un format binaire comme Word. De plus, il est agréable de disposer d'un accès via Internet afin de pouvoir consulter et travailler sur les documents au sein d'une équipe distribuée sans que les membres de l'équipe n'aient à installer de logiciel supplémentaire.

Answer 4

Voici un résumé des options et de mon expérience en 2017 :

(extrême 1) Complètement externe (par exemple, un wiki, Google Docs, LaTeX, MS Word, MS Onedrive)

• Les gens ne se soucient pas de le mettre à jour (la moitié d'entre eux ne savent même pas où trouver la page qui doit être mise à jour, tant elle est éloignée des tranchées).
• les plateformes wiki sont des "interfaces utilisateur captives" - vos données sont stockées dans leurs schémas propriétaires et ne sont pas faciles à examiner avec un simple éditeur de texte (Confluence est encore pire en ce sens que vous n'avez plus du tout accès au contenu en clair).

(extrême 2) Complètement interne (par exemple, javadoc)

• pollue le code source et est généralement de trop bas niveau pour être utile. Un code source bien écrit reste la meilleure forme de documentation de bas niveau.
  • Cependant, j'ai l'impression package-info.java sont sous-utilisés.

(solde) Colocalisé la documentation (par exemple README.md)

• Une bonne solution à mi-chemin, avec les avantages du contrôle de version. Si un seul README.md n'est pas suffisant, envisagez un fichier doc/ dossier. Le seul inconvénient que j'ai constaté est la possibilité de contrôler à la source des graphiques utiles (par ex. png ) et risquent d'alourdir la base de données.
  • Une façon intéressante d'éviter ce problème est d'utiliser des outils de diagramme en texte clair (je trouve que les outils de diagramme en texte clair sont plus efficaces que les outils de diagramme en texte simple). Grapheasy y Diagramme de texte pour être une bouffée d'air frais).
• peut être facilement lu même si votre moteur de rendu change au fil des ans.

Le succès de Github est en grande partie dû à son README.md situé dans la racine du projet.

Un petit inconvénient de cette approche est que votre système d'intégration continue déclenchera une nouvelle compilation à chaque fois que vous modifierez le fichier README.md.

Answer 5

Si vous écrivez une documentation utilisateur versionnée associée à chaque version du produit, il est logique de placer la documentation dans le contrôle de source avec la version du produit qui lui est associée.

Si vous rédigez une documentation interne à l'intention des développeurs, utilisez une documentation automatisée du code source interne (javadoc, doxygen, annotations .net, etc.) pour la documentation au niveau de la source et un wiki de projet pour la documentation au niveau de la conception.