D'accord avec les sentiments de plusieurs affiches, de nombreux utilisateurs ne lisent pas la documentation. Dans mes expériences, il y a trois méthodes de documentation qui, lorsqu'ils sont utilisés ensemble, à en faire un outil puissant et utile.
Couche 1: L'Auto-Documentation Du Code
Autant que possible, faire de votre API nécessitent que peu de documentation que possible. Suivre (et de publier) des conventions de nommage de vos fonctions, les paramètres et les types de données qui font leur but évident. Le meilleur de la documentation est la documentation qui n'est pas nécessaire.
Couche 2: Soluces / Exemple De Code
Alors que beaucoup de gens ne sera pas lu par le biais de la documentation de l'API, de la lecture à travers des exemples de code est généralement considéré comme moins pénible (et pour certains, plus utile). Créer certains simples et d'exemples d'utilisation de votre API et de les publier séparément à partir de votre API docs. Couvrir autant de la commune de scénarios d'utilisation que possible. Tout cela ne peut pas donner aux utilisateurs le même degré de connaissance que l'apprentissage de l'API, il aura au moins donner de nombreux utilisateurs un point de départ. Même s'ils se contentent de copier-coller et des exemples de code et l'utiliser comme un squelette pour leur propre, ils seront au départ, avec la connaissance de code de travail et vous permettra de réduire le nombre de "débutants" questions et demandes de soutien que vous recevez.
Couche 3: Détaillée, Toujours-Mise À Jour De La Documentation
Si beaucoup de gens le lire ou pas, il est toujours important d'avoir une description détaillée de l'ensemble de la documentation disponible. Pour ce faire, je préfère utiliser le document générateurs comme Doxygen. Cela fonctionne particulièrement mieux si vous avez une sorte de processus de génération automatique. Pour notre projet, nous avons un serveur qui ne les nightly builds et aussi re-génère la documentation du projet, tous les soirs. De cette façon, tout le monde peut voir les plus up-to-date docs quand ils les afficher sur le web.
Document générateurs de donner plusieurs avantages. Tout d'abord, il est facile de garder votre documentation à jour à tout moment. Depuis les générateurs d'utiliser des commentaires et notation dans le code source pour créer leur sortie, à l'aide du document générateurs aussi encourage les développeurs à fond et bien documenter son code (de cette façon, la documentation est à la source et en externe docs, et vous n'avez qu'à l'écrire une fois). Si votre projet contient plusieurs branches, ou vous avez des développeurs qui travaillent sur plusieurs versions différentes de votre code, un document générateur permet de créer de la documentation pour quelle que soit la version du code source qui est utilisé. Aussi, la génération automatique de la documentation ne nécessite aucun effort supplémentaire pour sauvegarder ou archiver (car il peut être re-créé à partir du code source qui vous maintiennent dans un référentiel de contrôle de version, non?).
Dans mes expériences, en offrant à ces trois couches de la documentation donne de meilleurs résultats. Ceux qui veulent lire des docs et d'apprendre l'API peut le faire, et ceux qui ne peuvent s'en sortir assez bien sans le faire. De votre point de vue, cette méthode requiert un minimum d'efforts. La première couche est quelque chose que beaucoup de projets de logiciels le font déjà. La deuxième couche est habituellement le cas dans la forme de la copie des sections de code que vous avez déjà écrit, en simplifiant, et en la publiant sur un site web ou un wiki. La troisième couche peut nécessiter un peu de travail pour le re-formater les commentaires existants pour suivre les conventions utilisées par votre générateur de documentation; cependant, Doxygen (et probablement d'autres) peut générer une assez bonne série de docs, même sans ajout de Doxygen-format de commentaires.
