Créer de la documentation

Bonjour tout le monde,

Voilà, j'entame d'ici une grosse semaine maintenant une formation de trois ans en informatique de gestion (donc programmation aussi bien en java, qu'en C++ ou en PHP). Je cherche à m'avancer un minimum sur les cours pour me faciliter la vie après. J'ai, entre autre, un cours d'Anglais où une des évaluations consistera à créer une documentation de codes en Anglais (of course).

Hors, malgré plusieurs années à programmer pour le web, mais en pur solo, je ne me suis jamais penchée sur la question de la documentation. Je cherche donc des tutoriels et/ou des informations plus théoriques et/ou des exemples bien fait sur comment faire une bonne documentation, ce qu'elle doit comporter, les termes qui lui sont propres, le type de présentation généralement utilisée,...

Bref, Comment on crée une documentation bien foutue ?

Un grand merci à tous ceux qui pourront m'aider ^^ (puis même hors des cours, je suis certaine que c'est une question qui taraude certains qui n'osent pas la poser)

Un certain nombre de langages ont un générateur de documentation dédié. Je pense entres autres à Java avec sa javadoc.

Avec un outil comme celui-là, tout ce que tu as à faire c'est placer tes commentaires selon les conventions de l'outil. Pour javadoc en général c'est /** ... */ (note la seconde étoile), avant la classe/méthode/constante que tu documentes, et des indications spécifiques sous forme de tags, p.ex. @param, @returns, @throws...

LE générateur s'occupe ensuite automatiquement de lire ton code et le convertir en un dossier de pages HTML normalement assez bien fichu.


Après, d'autres outils non spécifiques à un langage particulier se sont inspirés des principes généraux de la javadoc, qui était apparament assez révolutionnaire au moment où il a été proposé pour la première fois. Ca doit historiquement être un des premiers outils pour produire de la bonne doc automatiquement à partir du code.

Pour C++ les gens semblent souvent utiliser doxigen, et il me semble qu'il va aussi pour PHP. IL existe plein d'autres de ces outils pour plein d'autres langages, tu en trouveras sûrement en cherchant "générateur de documentation". En général ils produisent tous des dossiers au format HTML; il en existe pour d'autres formats, comme le CHM par exemple, mais c'est moins courant et pas forcément gratuit.

Après pour la formulation et les termes utilisés, le mieux c'est de s'inspirer des docs existantes afin de reprendre leur style d'écriture. ON peut le faire en mode très compact où on décrit brièvement le but de chaque méthode, ses paramètres et son retour en quelques phrases suivies, ou en mode complet où on décrit avec précision le rôle de chaque paramètre et d'où vient le retour, en précisant tous les cas particuliers et toutes les exceptions possibles.
J'ai l'impression que la tendence générale c'est de faire du mode complet en Java, C++ et PHP, et du mode plus détendu en python, lua, JavaScript, ruby et autres langages dynamiquement typés, où on peut déjà en faire dire beaucoup simplement avec les noms des classes, méthodes et paramètres.
Modifié par QuentinC (06 Sep 2015 - 10:11)

pour javadoc je l'avais découvert... Mais j'ai un énorme doute sur le fait qu'on nous laisse faire faire le boulot par la machine, surtout dans un cours de langue. Je ne cherche donc pas un outil me permettant de le faire, mais plutôt des ressources pour apprendre à les créer à la main.

Quasiment plus personne ne fait de doc technique à la main. Ces outils sont beaucoup trop pratiques une fois qu'on y a goûté. La seule chose à documenter c'est le code, on n'a plus rien à faire d'autre à côté.

C'est comme avec les frameworks: ça paraît hyper lourd, mais on décide d'y passer quand on en ressent vraiment le besoin, et après avoir essayé on ne reviendrait jamais en arrière.

Mais si tu veux vraiment le faire à la main, je partirais sur markdown+pandoc. Ca te permet de rédiger ton contenu très facilement en texte brut légèrement balisé et de le convertir en HTML. Par contre ça ne fait pas de CSS du tout.

Autre possibilité, LaTeX; mais c'est tout de suite plus compliqué. L'avantage c'est que c'est extrêmement puissant, tu peux tout faire avec. Ou alors, ton logiciel de traitement de texte habituel comme Word ou OpenOffice si ça t'amuse, mais ne compte pas sur eux pour qu'ils crachent du bon code HTML que tu pourras retravailler après. JE ne m'étenderai pas sur PDF, tout le monde sait déjà ce que j'en pense.

En ce qui concerne la rédaction du contenu proprement dit et sa forme, je l'ai déjà dit, le mieux est sans doute de s'inspirer de ce que tu considères comme des bonnes doc. A ma connaissance il n'y a pas de véritable règle ou mode d'emploi de ce côté-là, excepté une RFC dont je n'ai pas le numéro qui revient sur le sens exact de must, should, shouldn't, will et won't dans un contexte technique, et dont les docs du W3C font systématiquement référence au début.
Modifié par QuentinC (07 Sep 2015 - 06:32)