Où mettre la documentation du code?

J'utilise actuellement deux systèmes pour écrire la documentation du code (j'utilise C ++):

• La documentation sur les méthodes et les membres de classe est ajoutée à côté du code, en utilisant le format Doxygen. Sur un serveur, Doxygen est exécuté sur les sources afin que la sortie soit visible dans un navigateur Web
• Des pages de présentation (décrivant un ensemble de classes, la structure de l'application, un exemple de code, ...) sont ajoutées à un wiki

Personnellement, je pense que cette approche est facile car la documentation sur les membres et les classes est très proche du code, tandis que les pages de présentation sont vraiment faciles à modifier dans le Wiki (et il est également facile d'ajouter des images, des tableaux, ...). Un navigateur Web vous permet de voir les deux documentations.

Mon collègue suggère maintenant de tout mettre dans Doxygen, car nous pouvons ensuite créer un gros fichier d'aide avec tout ce qu'il contient (en utilisant HTML WorkShop de Microsoft ou Qt Assistant). Ma préoccupation est que la modification de la documentation de style Doxygen est beaucoup plus difficile (par rapport à Wiki), en particulier lorsque vous souhaitez ajouter des tableaux, des images, ... (ou existe-t-il un outil de prévisualisation pour Doxygen qui ne nécessite pas de générer le code avant de voir le résultat?)

Qu'est-ce que les grands projets open source (ou fermé) utilisent pour écrire leur documentation de code? Est-ce qu'ils partagent également cela entre le style Doxygen et un Wiki? Ou utilisent-ils un autre système?

Quelle est la manière la plus appropriée d'exposer la documentation? Via un serveur / navigateur Web, ou via un gros fichier d'aide (plusieurs 100 Mo)?

Quelle approche adoptez-vous lors de la rédaction de la documentation du code?

Avoir toute la documentation dans un seul système au lieu de deux peut être un réel avantage. Des choses comme la sauvegarde et la restauration, le contrôle de version, la recherche globale, la recherche globale et le remplacement, la réticulation et, comme vous l'avez écrit, en mettant tous les documents dans un document final, fonctionneront généralement avec moins de "friction" lorsque vous n'avez pas à maintenir deux différents systèmes avec des capacités qui se chevauchent.

D'un autre côté, vous devez vous demander si ces avantages l'emportent sur la facilité de votre Wiki. Le cercle éditer / générer / affiner éditer / générer à nouveau peut être plus rapide avec votre Wiki. Je suppose que vous pouvez obtenir ce cycle assez rapidement avec doxygen en gardant vos pages de présentation en tant que sous-projet doxygen distinct. Vous pouvez utiliser les capacités de liaison externe de doxygen, qui n'est pas un remplacement pour un "aperçu rapide", bien sûr, mais un pas dans cette direction. Je ne l'ai pas fait par moi-même jusqu'à présent, mais je suppose que vous devez essayer cela par vous-même si vous voulez savoir si cela fonctionne dans votre cas.

Concernant les autres projets: je pense qu'un outil comme doxygen est principalement destiné à la documentation de bibliothèque. Si vous n'êtes pas un fournisseur de bibliothèques tiers et que tous ceux qui utilisent vos bibliothèques ont un accès complet au code source, la nécessité d'un outil comme doxygen est discutable. Dans notre équipe, par exemple, nous n'avons presque pas de documents externes en dehors du code, à l'exception des documents utilisateur final et des documents de nos modèles de base de données. Nos principaux outils pour ce type de documentation sont docbook et fop , ce qui nous donne des résultats satisfaisants.

Utilisez d'abord la documentation du code. Ajouter du wiki et d'autres méthodes, si possible

Je sais que ça va être difficile de le maintenir.

Réponse pratique:

Concrètement, la première chose que font les développeurs, c'est de vérifier le code.

En tant que développeur, j'aime avoir une documentation externe, comme des wiki (s), des manuels. Mais, la première chose que je fais, c'est de revoir le code (parfois d'autres développeurs, parfois le mien).

En tant que développeur, qui a travaillé dans plusieurs projets et clients, je fais autant que possible d'ajouter de la documentation externe, mais, il est courant d'avoir beaucoup de charge de travail et de ne pas pouvoir supporter un wiki.

Parfois, les chefs de projet et autres patrons ne se soucient pas de la documentation, parfois d'autres développeurs ne s'en soucient pas.

Et, le mieux que je puisse faire, c'est d'ajouter des commentaires au code.

Bonne chance

Certains utilisent d'autres systèmes - jetez un œil au Sphinx de Python par exemple, ils ont un système de documentation tout-en-un qui construit tout (cela fonctionne également pour C / C ++)

Je pense toujours que la documentation est séparée du code, doxygen est génial, mais c'est pour un aperçu de l'API, pas de la «documentation». Pour cela, un wiki est génial, mais je préfère utiliser ASCIIDOC et stocker les résultats de celui-ci dans le contrôle de code source avec le code, principalement parce que je peux en générer des PDF à la disposition d'autres personnes (par exemple, les testeurs, le client, etc.)

Doxygen vous permet de créer des pages PDF, HTML, wiki, presque tout ce à quoi vous pouvez penser.

Ma préférence personnelle est d'avoir à la fois Doxygen et wiki et un script ou quelque chose pour vérifier quand ils divergent.

Depuis la version 1.8.0, doxygen prend en charge Markdown , ce qui devrait rendre l'expérience de l'écriture de pages statiques aussi pratique que dans un système Wiki.

Public cible

Je pense que lorsque vous répondez à cette question, vous devez vraiment vous demander qui est censé lire cette documentation. Un développeur a des besoins très différents d'un utilisateur ou même d'un analyste métier.

• En tant que développeur: documentation associée au code à l'étude, détails tels que le contrat d'interface et exemples d'utilisation. Peut-être une documentation de haut niveau et des spécifications de protocole pour faire bonne mesure.
• En tant qu'utilisateur: documentation disponible via le menu d'aide ou un site Web accessible sur la façon d'utiliser le logiciel.
• En tant qu'analyste commercial: la documentation disponible sous forme de documents ou en tant que site Web accessible est utile. Une quantité modeste de détails sur les protocoles, l'architecture de haut niveau et les cas d'utilisation sont les meilleurs.

Entretien

Quant à savoir où placer la source de cette documentation dépendra de votre public, et qui écrit pour votre public.

• Vous n'avez qu'une maison de développeurs? Placez tout dans le code. Il encouragera sa mise à jour. Vous devrez travailler sur une culture qui encourage les mises à jour de la documentation à être aussi importantes que les modifications de code.
• Vous avez une maison de développeurs et de rédacteurs de documentation? Répartissez les responsabilités. Utilisez les outils destinés aux développeurs pour les développeurs, utilisez les outils de rédaction de documentation pour les rédacteurs de documentation.

Dans la mesure du possible, assurez-vous que des exemples de code ou des cas d'utilisation peuvent être exécutés. Automatisez leur exécution et signalez en interne les défaillances. Il y a de fortes chances que ces pages soient de mauvaise ou mauvaise documentation.

De plus, quels que soient les outils dans lesquels vous choisissez d'écrire votre documentation, vous avez besoin d'un moyen fiable pour associer une version spécifique de la documentation à une version spécifique du code. Cela est toujours bénéfique même dans les nuages ​​heureux avec un seul déploiement à feuilles persistantes.

Intégration de la documentation

L'intégration peut être nécessaire pour produire de la documentation, mais notez que seul l'utilisateur s'attend à ce qu'un seul endroit accède à toute la documentation dont il a besoin.

L'analyste commercial est très satisfait d'une spécification d'API, des spécifications de conception et des scénarios d'utilisation qui doivent être situés dans des documents séparés ou des sections distinctes d'un site Web.

Le développeur préfère tout ce qui est visible depuis la source, mais il est tout à fait heureux d'avoir quelques documents de conception de haut niveau et des documents de spécification de protocole détaillés externes au code, bien que de préférence dans la même caisse.

Ton cas

Pour être honnête, la documentation de votre wiki n'est probablement pas la même sorte de documentation dans votre base de code. Il ne serait peut-être pas logique de fusionner le trop.

D'un autre côté, l'intégration des deux peut être réalisée de plusieurs manières simples.

• Les outils de documentation source (comme doxygen) peuvent produire du html, et un wiki vit sur un serveur web. Ce serait un simple point d'intégration de simplement servir une version construite aux côtés du wiki et de relier les deux.
• Certains produits wiki vous permettront d'exécuter le wiki directement à partir d'un fichier que vous pouvez archiver dans une base de code. Cela donne un outil wysiwyg simple tout en conservant la documentation associée au code.
• D'autres formats tels que le pdf peuvent également être adaptés, mais cela dépendra de l'outillage spécifique que vous souhaitez utiliser. Il pourrait être judicieux de gratter votre wiki dans des fichiers de démarque et de le nourrir via doxygen (ou d'autres outils). Il peut être judicieux de pdfer le wiki et la source séparément et d'utiliser un outil de fusion pdf.

À la fin de la journée, déterminez quel système de documentation a de faibles coûts de maintenance et vous aide à fournir un produit de haute qualité vu par votre public de développeurs, d'analystes commerciaux et d'utilisateurs. Tout ce qui gêne l'un de ces groupes réduira nécessairement la qualité des produits.

Si vous utilisez ASCII, vous devez stocker votre cache de vos données de documentation dans la partie haute de votre code source! Ensuite, seuls les utilisateurs les plus intelligents (lire: méritants) ont la possibilité d'utiliser vos documents.

Avoir de la documentation dans un format portable bien défini, facilement exportable pourrait être le véritable avantage. Si le sphinx meurt (peu probable), je devrai simplement me convertir à un autre système, ce qui, je suppose, serait une tâche scriptable. Déplacer des données hors du wiki (vraisemblablement stockées dans la base de données dans un format propriétaire peut être difficile).