Gestion de la documentation
Julien Peloton (IJCLab/CNRS)Documentation: de quoi parle-t-on ?
Specifications du code
Documentation du code
Manuel/aide utilisateur
Howtos/tutoriels
...
Pourquoi personne
ne veut le faire ?
Lu ou entendu
- Documentation is boring. Writing help files is even more mind numbing.
- I don't know anyone who reads user manuals except as a last resort.
- Most programmers are very lazy. Writing comments is just more work.
- Programmers dislike doing things that are not programming. It's an ego thing.
- Reading the code is the best way to know how a program works.
- Too many customers require documentation, but have no clue on what should go into it. We are programmers, not magicians or mind-readers.
- Documentation and programming are two entirely different skillsets
- Vague requirements like "...and it has to be documented!". No indication on indended users or usage, nothing on what it should describe. Nothing.
- Programmers are interested in ideas, and once the ideas are fixed concretely we lose interest in their communication.
- Programming is a largely a creative, problem-solving effort. Documenting is largely a teaching and communication effort.
- and so on...
Concrètement, beaucoup de mauvaise foi, mais aussi des barrières réelles
- Avoir une approche de la programmation qui ne se résume pas uniquement à coder.
- Connaître les bonnes pratiques et se former sur les outils
- Communiquer autour de son code
- Composer avec des backgrounds differents
- Faire valoriser ces compétences dans son travail
Programmer ⊃ coder
Avant de commencer
Une part importante dans la vie d'un logiciel se déroule en dehors du code.
Cela commence souvent par l'écriture des pré-requis et des spécifications, qui seront ensuite convertis en code.
Example avec l'Observatoire Rubin.
Concept de programming by contract: documenter les obligations contractuelles du logiciel dans un format lisible par machine, et documenter les intentions derrière les obligations en anglais/français.
Pendant le développement
Question: quand doit-on écrire la documentation de son code ?
- Principalement avant
- Parfois pendant
- Rarement après
La dette est d'autant plus grande que l'on attend...
Pendant le développement
Question: Que doit-on écrire dans son code ?
Tout ce qui pourrait ne pas être évident pour quelqu'un d'autre que l'auteur (y compris l'auteur dans un an).
En pratique, pre et post-conditions pour les méthodes, utilisation prévue des variables, tout ce qui est susceptible d'être mal compris par quelqu'un qui n'aurait pas écrit l'intégralité du code, et pas seulement le bout de fonction que l'on est entrain de lire.
Le code est aussi de la documentation
def toto(a, b):
""" worst case scenario
"""
return b[a]
def extract_value_from_dict(key: str, data: dict) -> float:
""" better scenario
"""
return data[key]
Autour du code
Question: une fois le code écrit, est-ce que la documentation va au-delà ?
Souvent oui: écriture d'un manuel utilisateur, tutoriels, publication de la documentation en ligne ou en ligne de commande, ... Cela va dépendre de la portée de votre travail. Identifiez les utilisateurs.
Bonnes pratiques et outils
Quelques bonnes pratiques
- La documentation doit être un processus continu, comme les tests.
- Suivez le style de code correspondant à votre langage.
- Envisagez de créer un template au sein de votre équipe pour la documentation au niveau du projet.
- Utiliser des outils pour générer de la documentation à partir du code source.
- Utiliser les outils de l'IDE.
- Automatiser le plus possible la chaîne!
Avant d'écrire le code
C'est l'étape de Software Design Documentation. Cela peut aller du simple fichier texte, à l'utilisation de logiciel de projet plus complexe, mais cela reste une étape "haut niveau".
L'idée est de décrire avec des mots, des diagrammes, des relations, les différentes parties du futur logiciel.
Dans le code
Automatiser la génération de documentation
def function(arg):
"""
A short description.
A bit longer description.
Parameters
----------
arg : type
description
Returns
-------
type
description
Raises
------
Exception
description
Examples
--------
Examples should be written in doctest format, and
should illustrate how to use the function/class.
>>>
"""
pass
Autour du code: publication de la documentation en ligne
Il existe des outils pour facilement extraire la documentation du code, et la formatter pour une publication sur le web, e.g. sphinx (API reference).
Ces outils permettent aussi d'étoffer la documentation, et d'ajouter du contenu autour du code. L'hébergement peut se faire facilement sous GitLab/GitHub (avec intégration continue).
Voir aussi readthedocs ou mkdocs
Autour du code: tutoriels
Mettre la documentation du code en ligne OK. Mais comment on utilise le code ?
La présence de tutoriels est souvent très appréciée. Ces tutoriels peuvent être inclus dans la doc du code (e.g. doctest), ou en plus (e.g. quickstart).
Communiquer autour de son code
Identifier les utilisateurs du code
Qui va utiliser le code :
développeurs? internes/externes? scientifiques? grand public?
Quel genre d'utilisation :
implémentation de nouvelles fonctionnalités bas niveau? utilisation d'API haut niveau? Interface graphique ou ligne de commande?
La revue de code: c'est aussi pour la doc !
La documentation doit faire l'objet du même traitement que le code lors d'une revue de code.
Ca suppose aussi que les règles sont connues de toutes et tous. L'équipe doit être formée, et les utilisateurs extérieurs doivent pouvoir trouver l'information (e.g. README).
Le tutoriel: l'arme de conversion massive
Mieux que 20,000 lignes d'explication, mieux qu'un long discours, l'exemple est un outil puissant pour présenter le fonctionnement du code.
Un bon tutoriel bénéficie du retour de la communauté d'utilisateurs.
Composer avec des backgrounds différents
Tous les chemins mènent à l'informatique
Contrairement à d'autres disciplines, l'informatique touche un grand nombre de communautés diverses. Ce qui est trivial pour l'un, ne le sera pas forcément pour l'autre.
Faire valoriser le travail de documentation
La doc c'est chiant, c'est long, et ça ne paye pas
Les clichés ont la vie dure. On nous demande souvent d'écrire un code qui marche.
On nous dit que les gens ne lisent pas la doc non plus, et puis il n'y pas de place pour "du blabla" ou des "tutos rigolos" sur la fiche de paie ou l'évaluation annuelle.
Et puis de toute façon, si le chef de projet est relou, on se casse sur un autre projet. Qu'est-ce qu'on a raté ?
Le mot de la fin
Pour être efficace, la gestion de la documentation doit être vu comme un bénéfice pour celui ou celle qui l'écrit.
Et s'il était temps que le travail de documentation soit reconnu comme une partie intégrante du travail de développeur, avec donc des formations ? Et si la qualité du logiciel passait aussi par l'évaluation de sa documentation ?
Ah ah looser, la doc c'est chiant, moi je code tellement bien que tout le monde comprend sans le blabla.
A retenir
- La documentation doit être un processus continu, comme les tests.
- La documentation doit être présente à toutes les phases de développement.
- Identifier les utilisateurs du code pour cibler au mieux la documentation.
- Utiliser des outils, et automatiser le plus possible la chaîne!