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:
- 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.
- Fondamentaux.
Pour les gars désireux d'apprendre rapidement les choses nécessaires pour commencer à produire des logiciels qui fonctionnent.
- 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 .
- 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.
- 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.
Votre public secondaire est responsable du manuel. Ces gars-là peuvent faire ou défaire la façon dont les choses fonctionnent pour votre public principal, alors vous feriez mieux de prendre soin de leurs besoins et de leurs problèmes.
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:
- 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é.
- 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 .
Des concepts tels que les stratégies de verrouillage, les détails liés aux performances devraient être inclus (éventuellement partiellement) là où vous vous attendez à ce que le public cible en ait besoin.
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?