Documenter un langage de programmation: Manuel de référence

Nous examinons la refonte de la documentation sur notre gamme de produits. Une partie de cela comprend des manuels de référence pour un langage de programmation utilisé dans le cadre du système.

Lors de la rédaction d'un manuel de référence pour un langage de programmation, quelle est la meilleure façon de le structurer pour une utilisation maximale pour les nouveaux utilisateurs du langage?

Quels sont les aspects clés pour chaque mot clé documenté?

• Syntaxe
• La description
• Arguments - le cas échéant
• Valeurs de retour - le cas échéant
• Exemple d'utilisation?
• En manque-t-il d'autres?

Les concepts (tels que les stratégies de verrouillage, les détails liés aux performances) devraient-ils également être documentés dans ce manuel de référence, ou s'agit-il d'un document distinct?

_{C'est pour la consommation externe. Nous avons déjà des ensembles de documents complets (voir: http://www.rocketsoftware.com/u2/resources/technical-resources ). Déterminer ce que nous devons faire différemment - j'ai déjà mes idées, mais comme toujours, j'essaie de ne pas me fier uniquement à mon opinion.}

_{Public: développeurs techniques utilisant nos bases de données et nos outils pour produire des logiciels dans de nombreuses industries.}

Organisez la documentation en fonction des besoins du public cible.

Dans votre cas, le public principal est apparemment des développeurs de logiciels. Les parties à considérer ici sont destinées aux différents "sous-publics" de celui-ci:

1. Bonjour le monde.
   Ceux qui veulent en avoir rapidement le goût, il suffit de créer et d'exécuter un exemple d'application pour voir à quoi il ressemble.
   Pensez à l'audience comme celle abordée par MySQL "règle des 15 minutes" :
   

   _{... un utilisateur pour que MySQL soit opérationnel 15 minutes après avoir fini de le télécharger.}

2. Fondamentaux.
   Pour les gars désireux d'apprendre rapidement les choses nécessaires pour commencer à produire des logiciels qui fonctionnent.
3. Sujets avancés.
   Pour les développeurs déjà bien familiarisés et habitués aux fondamentaux, intéressés à savoir ce qu'il y a au-delà. Sujets courants qui n'ont pas été traités dans les fondamentaux .
4. Guide de style / pratiques recommandées.
   Des conseils et des conseils subjectifs pour ceux qui s'intéressent à la façon dont vous recommandez de faire les choses.
   _{La question n'indique pas si cela pourrait avoir un public important dans votre cas, donc les options à considérer sont de l'inclure en tant que partie / annexe de sujets avancés ou même de le supprimer complètement.}
5. Quirks.
   Sujets obscurs, en dehors du courant dominant, qui pourraient intéresser une fraction assez limitée de votre public. Par exemple, si vous avez une ligne héritée, ou des choses comme la mise à niveau / la migration / l'interopérabilité avec l'héritage - mettez-la ici. S'il y a des effets secondaires pour certaines fonctions dans un environnement "exotique" particulier, cela va dans cette partie.

^{Que faire si quelque chose dans le manuel est discutable / ambigu? Que se passe-t-il s'il s'avère qu'une explication approfondie de concepts particuliers rendrait ce manuel trop difficile à lire? Et s'il s'avère que cette version particulière du manuel contient des erreurs?}

Deux choses à considérer pour les responsables sont:

1. Spécifications techniques / formelles.
   Chaque fois qu'il y a un sujet discutable / ambigu / difficile à expliquer dans le manuel, le lecteur peut être renvoyé à un paragraphe particulier de la spécification pour une déclaration "officielle" stricte et claire à ce sujet. Une description stricte et complète (et probablement ennuyeuse) de la syntaxe du langage ferait mieux d'y aller.
   Les considérations primordiales pour la spécification sont la précision technique et l'exhaustivité, même si elles se font au détriment de la lisibilité.
2. Supplément en ligne.
   Il suffit de réserver une URL et de la mettre au début de chaque document que vous publiez, afin que les gars qui se demandent ce qu'ils viennent de lire puissent y aller (au lieu de harceler les mainteneurs manuels) et trouver l'erreur expliquée.

   _{Errata> Principes fondamentaux> Version 2.2> Faute de frappe à la page 28, la deuxième phrase commence par la chance , lisez plutôt le verrou .}

Par exemple, les mainteneurs manuels seraient apparemment intéressés par une description complète et précise de la concurrence et du verrouillage dans la spécification formelle - mettez-la là. Les lecteurs de sujets fondamentaux ou avancés pourraient être intéressés par une vue d'ensemble / introduction / guide extrait des spécifications et adapté à leurs besoins, etc.

_{Il pourrait être utile d'organiser une étude comparative de la documentation de référence fournie pour d'autres langues comme la vôtre. Cette étude vise à tirer parti de l'expérience acquise par ceux qui l'ont déjà fait et à apprendre à éviter les erreurs qu'ils ont commises.}

_{Le dernier mais non le moindre, envisagez de configurer le développement de la documentation d'une manière similaire au développement logiciel. Je veux dire des choses comme le contrôle de version, les versions régulières, le suivi des problèmes, l'assurance de la qualité, etc. Nous ne voulons pas obtenir du contenu merdique "en échange" d'un processus de développement parfait, n'est-ce pas?}

La première chose que vous devez faire est d'évaluer le public. Votre public est-il des hackers du noyau Linux ou sont-ils des concepteurs de matériel qui utilisent des outils logiciels pour faire un travail mais ne sont pas intéressés par les logiciels en eux-mêmes et n'ont pas d'expérience en CS. Les ingénieurs électriciens ne sont probablement pas complètement clairs sur les différences entre les arguments const et non const, les pointeurs vers les objets par rapport aux références, etc. Si vos primitives ont des noms surchargés, vous feriez mieux d'expliquer ce concept à un niveau approprié pour votre public, ce qui pourrait ne rien être s'ils sont des programmeurs C ++.

La deuxième chose que vous devez évaluer est la granularité des primitives du langage. Plus la granularité est fine, plus vous devrez fournir des exemples d'utilisation à proximité des spécifications de syntaxe de chaque primitive. Autrement dit, si vous avez une primitive de bas niveau qui instancie un certain contexte, et que vous devez opérer dessus avec trois autres primitives de bas niveau avant de pouvoir faire quoi que ce soit d'utile, alors vous feriez mieux d'avoir un exemple complet de quelque fonction utile close- par dans le manuel. Voir la documentation openssl en ligne pour un excellent contre-exemple de documentation presque inutilisable.

Assurez-vous d'inclure une explication des effets secondaires de vos fonctions.

Dans tous les cas, si vous ne voulez pas que les programmeurs de votre client vous maudissent chaque nuit avant de vous coucher, incluez beaucoup d'exemples de code testés qui exécutent des primitives fonctionnelles de haut niveau. Assurez-vous que les exemples ne sont pas uniquement des extraits de code, mais qu'ils sont complets et compilables ou exécutables prêts à l'emploi.

Traditionnellement, les rédacteurs technologiques ont fait la distinction entre les manuels de référence et les guides d'utilisation . Le manuel de référence comprend généralement les spécifications de syntaxe, une définition intelligible des fonctions ou des primitives, une discussion sur le gotcha, les performances et les effets secondaires, et un court exemple d'utilisation. Le guide de l'utilisateur comprend des exemples d'utilisation plus étendus et une discussion sur des problèmes d'ingénierie plus larges. Le «langage de programmation C» de Kernigan et Ritchie est un excellent contre-exemple à cette convention, mais cette approche ne fonctionne que lorsque le langage que vous documentez est relativement simple.

L'auteur a été directeur de la division des services d'ingénierie au centre de développement de Ready Systems Inc entre 1987 et 1991, chargé de gérer une équipe de cinq rédacteurs technologiques.