L'utilisation GAML pour la documentation conceptuelle de la bibliothèque [fermée]

Question

Je travaille sur une nouvelle bibliothèque et j'utilise des commentaires XML pour la documentation de l'API avec SandCastle qui fonctionne très bien.

Mais je dois écrire la documentation supplémentaire qui couvre les concepts, l'architecture générale, des démonstrations de travail, etc., des diagrammes de classes etc.

J'ai 2 options:

1. Utilisez un moteur de wiki et écrire la documentation style wiki.
2. Utilisez GAML qui semble être à cet effet.

L'utilisation wiki semble solution sûre car il y a beaucoup stables, populaires et moteurs disponibles gratuitement, mais l'API et la documentation conceptuelle ne va pas de pair (réticulation, apparence, etc.). L'utilisation GAML signifie une courbe d'apprentissage et je ne suis pas sûr de la façon dont la maturité, il est et quels sont ses avantages / inconvénients.

Avez-vous utilisé GAML / Wiki à cet effet et quels ont été vos apprentissages? Que voulez-vous me suggérer?

Answer 1

Personnellement, j'aime la liberté de travailler w / un wiki. À ce stade, vous avez quelques choix décent pour l'édition GAML

• DocProject
• Sandcastle Help File Builder

Je ne peux pas parler beaucoup à DocProject (mais il semble bien). En ce moment, j'utilise SHFB pour fusionner la documentation de l'API et des documents conceptuels dans GAML. L'éditeur est décent et plus suffit à mes besoins. Je suis en mesure de mettre facilement une table des matières et lien entre mon API et les documents conceptuels. Une bonne ressource pour regarder des exemples est SandcastleStyles .

Comme toutes choses, il y a des questions importantes à poser.

• Avez-vous des conditions requises pour expédier vos documents dans un seul paquet? Dans mon cas, il me fallait expédier tout dans un joli paquet compilé. Vous ne pouvez pas faire w / un wiki, mais vous pouvez le faire avec / Sandcastle.
• Vous allez être la seule personne mise à jour du contenu conceptuel? La plupart des wikis ont un éditeur vraiment sympa et une capacité de relier rapidement entre les sujets. Le seul outil dont vous avez besoin de modifier le contenu est un navigateur, ce qui pourrait être une exigence pour un écrivain techniquement moins avertis.