Comment gérer la documentation d'un projet open source? [fermé]

12

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?

TaylorOtwell
la source
1
Bien que je n'ai pas vraiment de réponse, je suis tombé sur ce blog sur la gestion de la documentation avec le wiki github. cach.me/blog/2010/12/… Vous pouvez le trouver utile.
Jacob Schoen

Réponses:

6

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

Martin Beckett
la source
7
À mon avis, la documentation générée à partir des fichiers source est nécessairement mais rarement suffisante. Une documentation adéquate doit toujours inclure de nombreux exemples non triviaux ainsi qu'un didacticiel pas à pas. De plus, la documentation générée à partir du code source est aussi bonne qu'une documentation intégrée au code source.
Adam Crossland
Je ne voulais pas dire généré automatiquement à partir du code. Je ne veux pas dire que si vous mettez une explication de ce que fait une fonction, elle doit être à côté de la fonction ou elle n'est pas mise à jour. Vous pouvez toujours mettre une documentation d'introduction dans une intro.h distincte. Ceci est particulièrement important pour une bibliothèque où vous avez besoin de documents précis par fonction
Martin Beckett
4

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.

Karl Bielefeldt
la source
1

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.

S.Lott
la source
0

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.

Mathias Verraes
la source
1
Pourriez-vous expliquer davantage ce qu'il fait et pourquoi le recommandez-vous comme répondant à la question posée? Les "réponses en lien uniquement" ne sont pas tout à fait les bienvenues à Stack Exchange
gnat