Je suis le créateur d'un projet open source en pleine croissance. Actuellement, je deviens frustré en essayant de trouver la meilleure façon de gérer la documentation. Voici les options que j'ai envisagées:
- Site Web HTML
- Un wiki Github
- Fichiers Markdown hébergés sur Github
- Placer tous les documents dans Github README.md
La documentation est déjà écrite dans Markdown, je n'arrive pas à comprendre comment je veux la rendre disponible. Je suis vraiment attiré par Git car je peux créer des branches et étiqueter la documentation comme je peux créer des branches et étiqueter la source.
Je pourrais utiliser une bibliothèque Markdown pour traduire le Markdown en HTML et l'afficher sur un site Web de style. J'aurais besoin de télécharger des modifications sur le site Web chaque fois qu'il y aurait un changement, et il serait difficile de gérer toutes les différentes «balises» de la documentation.
Les wikis Github (pour autant que je sache) ne changent pas selon la branche sur laquelle vous vous trouvez. Donc, je ne pouvais avoir la version "maître" de la documentation sous forme de Github Wiki à un moment donné.
Tout mettre dans le Github README est un peu soigné. Je reçois des branchements et des balises, mais c'est un peu fatigant à utiliser et ne se prête pas bien à une navigation facile.
Suis-je en train de manquer une solution géniale? Quelles autres options ai-je?
la source
Réponses:
Une chose que je dirais est que la documentation DOIT être dans les fichiers de code source (en utilisant le balisage que vous voulez), puis les documents générés automatiquement à partir de ceux-ci.
Au moins sur votre site, vous pouvez générer des téléchargements formatés des documents dans le cadre du package source afin que l'utilisateur n'ait pas besoin d'un outil de documentation spécifique
La possibilité que quelqu'un d'autre corrige / ajoute une fonction, puis édite / ajoute un peu de documentation de balisage immédiatement adjacente dans le même fichier peut être faible MAIS la chance pour eux de trouver un fichier complètement différent dans un référentiel de documents différent pour faire de même est légèrement moins que zéro.
Vous pouvez toujours avoir un tutorial.h qui contient de gros blocs de texte si vous le souhaitez - mais le traiter comme faisant partie de la source
la source
Si votre projet est une bibliothèque, rien ne vaut la documentation de style javadoc pour documenter la syntaxe de l'API à partir des commentaires dans le code lui-même.
Quant à la documentation sur les tutoriels, les exemples d'utilisation, etc., je recommande fortement d'utiliser un format wiki. D'autres projets que j'ai vus ont des pages séparées pour différentes branches. Lorsque vous démarrez une nouvelle branche, il vous suffit de copier les éléments qui n'ont pas été modifiés sur une nouvelle page et de mettre à jour à partir de là.
Ma raison de recommander un wiki est anecdotique, mais par expérience personnelle. J'ai contribué à plusieurs reprises à la mise à jour de la documentation de projets open source, mais ils ont tous été sur des wikis. Si j'essaie de comprendre quelque chose et que la documentation est trompeuse ou inutile, après avoir compris, je mettrai à jour le wiki pendant que je suis dans la documentation et c'est frais dans mon esprit. Si ce n'est pas par sentiment de redonner, du moins parce que je sais que je devrai probablement le chercher moi-même dans un an ou deux.
S'il n'y a pas de wiki, la barrière à l'entrée est tout simplement trop élevée pour déranger, entre déterminer comment la documentation est générée, où elle est stockée, obtenir les dernières informations du contrôle de code source, comment effectuer des modifications, effectuer les modifications réelles, et parcourir les listes de diffusion pour faire accepter un patch.
Si vous souhaitez contrôler étroitement votre documentation, utilisez certainement ce qui vous convient le mieux, car vous serez le seul à la mettre à jour. Si vous souhaitez encourager la participation de la communauté, utilisez un wiki.
la source
Les fichiers Markdown hébergés avec la source fonctionnent extrêmement bien.
Les outils docutils basés sur RST , par exemple, peuvent créer du HTML ou LaTex (et PDF) à partir d'un ensemble de documents.
Ceci - en effet - combine votre option 1 et l'option 3.
la source
Si cela ne vous dérange pas de convertir les documents de Markdown en reStructuredText, pensez à Sphinx . C'est aussi simple que le démarque, mais c'est beaucoup plus puissant.
la source