9
votes

Documentation et contrôle de la version

Étant donné qu'un projet, je suis sur le point de commencer, il y aura une documentation produite.

Quelle est la meilleure pratique pour cela?

Les documents respectent-ils avec le code et des actifs doivent-ils exister un magasin de documentation séparé?

Modifier

Je voudrais un wiki mais je devrai imprimer les documents, etc. C'est un projet universitaire.


4 commentaires

Est-ce que cette documentation de niveau utilisateur ou la documentation du développeur est-elle?


C'est tout. Malheureusement, c'est un projet universitaire.


Les documents sont écrits au bureau par opposition à des documents en ligne et il s'agit d'un mélange de contenu manuel et généré automatiquement.


En ce qui concerne l'impression / l'exportation du wiki, pouvant être effectué avec des logiciels Wiki déjà construits tels que MediaWiki (qui gère Wikipedia). Est-ce ce que tu veux dire?


7 Réponses :


4
votes

le stocker dans le contrôle de la source va bien.


0 commentaires

10
votes

Cela dépend vraiment de votre équipe. Là où je travaille, nous gardons la documentation dans un wiki qui est relié au site Web de notre équipe. Aux fins de la documentation sur l'expédition, le wiki peut être exporté et nous l'exécutons à travers un analyseur qui "favorise" l'apparence et la sensation de la documentation à des fins du client.

stocker la documentation avec le code (typiquement dans votre référentiel source) n'est pas une mauvaise idée. Assurez-vous de les garder séparés. Par exemple, gardez un dossier docs situé au même niveau avec votre dossier src de votre référentiel. De cette façon, vous pouvez rapidement expédier la documentation actuelle, vous pouvez facilement suivre les révisions, et chacun nouveau dans le projet peut immédiatement sauter sans avoir à aller à plusieurs endroits pour obtenir des informations.


0 commentaires

0
votes

Si vous écrivez la documentation de l'utilisateur versé associée à chaque version du produit, il est logique de mettre la documentation dans le contrôle de source avec sa version de produit associée.

Si vous écriez la documentation de développeur interne, utilisez la documentation de code source interne automatisée (Javadoc, Doxygen, .NET annotations, etc.) pour la documentation de niveau source et un projet Wiki pour la documentation de niveau de conception.


0 commentaires

0
votes

Je pense que la plupart d'entre nous dans l'industrie ne suivent pas vraiment les meilleures pratiques et cela dépend bien sûr beaucoup sur votre situation.

Dans un environnement agile où vous auriez un processus de sortie très itératif, vous voudrez "voyager léger". Dans ce cas particulier, la suggestion de Jason d'un wiki séparé fonctionne vraiment bien.

Dans un modèle d'automne / Big Bang, vous aurez une meilleure occasion d'avoir une mise à jour de la documentation décente avec chaque nouvelle version. Vous devrez également documenter clairement la version des exigences et avoir des charges de documentation pour chaque petit changement que vous effectuez aux exigences (en raison des effets qu'il a sur des étapes ultérieures). Souvent si la documentation peut vivre avec le code source contrôlé par la version, c'est le meilleur.


0 commentaires

0
votes

Utilisez-vous une sorte de documentation automatique ou est-ce complètement manuel? En supposant que vous utilisiez un système de documentation automatique, la documentation est plus ou moins générée à la volée et ferait partie du code lui-même.

Pour moi, (supposant que c'est possible avec tout ce que vous utilisez), ce serait la méthode privilégiée de la manipulation, car vous n'avez pas besoin de maintenir la source de la documentation du tout.


0 commentaires

1
votes

Ceci est une question intéressante - essentiellement, ce que les autres disent ont raison à propos de la documentation générée, des fichiers source et des modèles / etc. doit être stocké dans le contrôle de la source et généré au cours de votre processus de construction.

en ce qui concerne les exigences / spécifications / etc. Documentation, j'ai travaillé à la fois et je préfère beaucoup utiliser SharePoint ou un portail Wiki / Document conçu pour le partage / la version de documents. La raison en est que la plupart des personnes non-développeurs ne sont pas à l'aise de travailler avec des systèmes de contrôle de source et que vous n'obtenez aucun des avantages de la fusion intelligente si vous utilisez un format binaire comme Word. De plus, il est agréable d'avoir un accès basé sur Internet afin que vous puissiez faire référence à la documentation dans une équipe distribuée sans que les gens doivent installer des logiciels supplémentaires.


0 commentaires

1
votes

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

(extrême 1) complètement externe (par exemple un wiki, google docs, latex, MS Word, MS OneDrive)
  • Les gens ne sont pas pris gênés de la garder à jour (la moitié d'entre eux ne savent même pas où trouver la page qui nécessite une mise à jour car elle est tellement hors des tranchées).
  • Les plates-formes Wiki sont des "interfaces utilisateur captives" - vos données sont stockées dans leurs schémas exclusives et ne sont pas faciles à examiner avec un simple éditeur de texte (la confluence est encore pire en ce que vous n'avez plus accès au contenu en plainte.

    (extrême 2) complètement interne (par exemple Javadoc)
    • pollue le code source et est généralement trop bas niveau à utiliser. Le code source bien écrit est toujours la meilleure forme de documentation de bas niveau.
      • Cependant, je sens package-info.java Les fichiers sont sous-utilisés.

        (Balance) Colocated Documentation (E.G. README.MD)
        • une bonne solution à mi-chemin, avec les avantages du contrôle de la version. Si un seul fichier readme.md n'est pas suffisant, envisagez un dossier doc / . Le seul inconvénient de ce que j'ai vu est de savoir si vous souhaitez maîtriser des graphiques utiles (E.G. PNG ) et le risque balloir le repo.
          • Un moyen intéressant d'éviter ce problème est d'utiliser des outils de diagramme en clairexuant (je trouve Grapheasy et Schéma de texte pour être une bouffée d'air frais).
          • Le texte en clair peut être facilement lu même si votre moteur de rendu change au fil des années.

            Le succès de GitHub n'est pas en une petite partie grâce à son fichier README.MD situé à la racine du projet.

            Un minuscule inconvénient de cette approche Bien que votre système d'intégration continue déclenchera une nouvelle construction à chaque fois que vous effectuez des modifications au fichier README.MD.


0 commentaires