La documentation est souvent vue comme ennuyeuse pour une tranche des
développeurs. Pas tous. Certaines aiment à rendre compte d'un bel ensemble avec
leur logiciel.
D'un autre côté, d'autres contributeurs tout à fait bien placés pour ça, aiment
remplir ce rôle.
Et bon nombre d'utilisateurs et développeurs sont contents de pouvoir compter
sur une documentation bien faite à portée de main.
Qui plus est, la documentation peut se retrouver sous diverses formes: dans des
documents à part, en ligne sur le web (ou dans un intranet), en ligne sur le
système (pages man ou info sur les systèmes Unix), dans l'arborescence du
projet, et même imbriquée directement dans le code !
L'idéal est de satisfaire tout le monde.
Le développeur aimera avoir la documentation attachée à son projet, dans son
système et sur le web.
L'utilisateur final aimera la documentation dans un document qui lui est facile
d'accès, en ligne et dans le gestionnaire d'aide de son système.
Heureusement, il y a des parties qui se recoupent.
Pour arbitrer la question, c'est l'usage des documents qui va parler.
Mais aussi... Qui est susceptible d'en être rédacteur...
La première question à se poser est peut-être celle-là: "Quel est le juste
niveau de documentation ?".
Cela revient à déterminer:
- Ce qu'il faut documenter
- Où il faut le documenter
- Jusqu'à quel niveau il faut le documenter
Là, il y a différentes pratiques, je vous invite à consulter quelques projets
open source connus, et à vous renseigner sur les usages de votre équipe de
travail, ces questions en tête.
Ensuite, la première chose à faire, c'est de commencer, de poser le contenu,
peu importe la forme. Non pas que la forme ne soit pas importante, qu'elle
n'ajoute pas de la valeur à l'ensemble, mais qu'elle peut être embellie
après.
Et l'utilisateur sera content de trouver une information utile, plutôt qu'un
joli tape-l'oeil vide de sens.
Vos idées, une fois qu'elles ne sont plus fraîches, elles, sont plus difficiles
à raviver. Si vous écrivez un jeu, notez de suite les règles dans un manuel,
même de manière synthétique, ce sera toujours plus simple que de relire toutes
vos boucles et conditions dans le code pour déterminer quelle est l'enjeu de la
victoire !
Maintenant, si vous avez une idée de design, notez-le, ça fait partie des
choses à se remémorer aussi !
Pour le format, dans le doute, commencez par quelque chose de simple.
Un simple fichier texte peut convenir, il a l'avantage d'être lisible partout,
de pouvoir visualiser d'un coup d'oeil ce qui a changé d'une révision à l'autre
et de ne pas passer trop de temps à trouver le bon formatage.
Oui, bon, c'est un geek qui parle....
N'oubliez pas que c'est la première étape, celle de conserver l'information.
Le formatage, vous pourrez l'enrichir après ; si vous devez changer d'outils,
vous êtes susceptibles de revoir tout ce formatage. Et, rappelez-vous, le
développeur n'aime pas faire 2 fois la même chose...
D'autant qu'il y a des outils qui viennent à son secours.
Il y a une multitude d'outils pour parvenir à produire la documentation au
format qui vous plaise, à vous et votre équipe.
Cela va du simple fichier texte écrit avec un éditeur au CMS complet, qui
établit un point entre le code et la documentation. En passant par le
traitement de texte, la documentation rédigée en HTML, la documentation en
ligne dans un Wiki ou autre CMS, et la documentation générée dans différents
formats de publication à partir d'un format d'édition.
Personnellement, je suis à la fois développeur, geek et, récemment graphiste.
J'attache donc de l'importance à ces critères pour ma documentation:
- un format ouvert et accessible à tous, sans nécessiter un outillage
spécialisé
- une documentation proche du code, pour des raisons d'accès, de disponibilité
et de maintenance
- un sens de l'esthétique
- une facilité d'édition et de visualisation des changements
- une diversité de formats de lecture
- la mise à disposition à travers le réseau (web ou intranet), au moins par le
biais du protocole HTTP
- la mise à disposition sur le système d'exploitation
Ce que j'ai trouvé pour y répondre, ce sont les outils de génération de
documentation.
Ils ont pour principe de partir d'un format source dans lequel la documentation
est rédigée, pour produire la documentation dans une variété de formats de
publication.
Voilà leurs caractéristiques:
- rédaction dans un format source, texte ou LaTeX, ou DocBook:
- format ouvert accessible à tous, à l'aide d'un simple éditeur de texte, en
particulier si la source est de format texte, y compris des formats axés
sur une mise-en-page (reStructuredText, markdown, org-mode, ...)
- visualisation des changements aisée en l'intégrant au suivi de version
- documentation proche du code: dans l'arborescence du projet, et même jusque
dans le code source du programme (combinaison des deux possible)
- export dans une variété formats
- diversité de formats de lecture, ouverts et accessibles à tous selon les
formats produits (texte, HTML, ePub, DocBook, LaTeX, PDF, Open Document
Format, man pages, info pages, ...)
- sens de l'esthétique, possibilité de rédiger des feuilles de styles pour
produire des documents orientés papier (LaTeX/DocBook), ou en ligne
(HTML/CSS)
- accès en ligne via le web pour les pages générées en HTML
- disponibilité sur le système d'exploitation (HTML, man, info)
Enfin, cet outillage rejoint de très près la philosophie Unix, "un outil pour
faire chaque chose bien":
- un compilateur pour produire une application à partir du code source
- un outil de génération pour produire un document prêt-à-lire à partir d'une
source d'informations pour la documentation
- un éditeur de texte pour rédiger du code et de la documentation,
c'est-à-dire les entrées des deux outils cités
Parmi les outils qui ont retenu mon attention, il y a:
- Pour Python:
- les docstrings (fonctionnalité de base): pydoc (https://docs.python.org/2/library/pydoc.html)
- pdoc (https://github.com/BurntSushi/pdoc) (amélioration pour les
doctsrings)
- Sphinx (http://sphinx-doc.org): production de documents hiérarchisés et
complets
- pydoctor (https://launchpad.net/pydoctor), une alternative à Sphinx
- Pour C/C++:
- Sphinx : il est capable de fonctionner en C/C++ et d'autres langages,
même s'il n'est pas utilisé jusqu'au bout de ses capacités
- asciidoc (http://asciidoc.org/ et http://asciidoctor.org/)
- doxygen (http://www.doxygen.org/)
- Autres langages: de nombreux langages ont leurs systèmes de génération de
documentation, renseignez-vous sur le web sur les meilleurs pratiques
Et n'oublions pas le fabuleux pandoc (http://pandoc.org/) qui se charge de
réaliser des conversions entre divers formats de représentation de la
documentation.
Ce qu'il manque dans tout ça: la possibilité d'éditer la documentation avec un
outillage usuel pour les contributeurs. Cependant, cela pourrait être réfléchi,
proposer une interface WYSIWIG dans un navigateur qui aide à saisir le contenu
de la documentation source.
Il y a une erreur de communication avec le serveur Booktype. Nous ne savons pas actuellement où est le problème.
Vous devriez rafraîchir la page.