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.