La Documentation comme une punition

L’autre matin encore, j’ai entendu mes collègues parler de leurs tâches possibles pour les prochaines heures, et l’un dire à l’autre : « Tu peux écrire la documentation de telle Story, si tu veux » et l’autre répondre : « Non, je ne suis pas désespéré à ce point. »

Mes collègues sont formidables et ils me donnent l’occasion de parler de cette tradition de voir la documentation de ses développements comme une punition. Évidemment, ce n’est pas la partie la plus sexy du code de se taper la Documentation. Evidemment, c’est pas l’fun de devoir expliquer ce qu’on a brillamment conçu avec son cerveau super-intelligent pour que d’autres péons puissent comprendre le fonctionnement, sinon l’intention de votre création.

Pillory (PSF)

Cloué au pilori, la punition

Simplement, si vous avez fait vos développements super-cools, qui va savoir les utiliser hormis vous ? Qui va savoir qu’ils existent si vous n’en faites aucune promotion ?

Pour moi, la documentation sert à plusieurs personnes :

  •  Le développeur qui est forcé d’expliquer et remettre à plat l’utilité et le fonctionnement de son oeuvre.
  • Les utilisateurs qui veulent s’en servir, qu’ils soient utilisateurs techniques ou non
  • Les autres collègues, incluant le développeur lui-même dans le futur, qui sont parfois forcés de reprendre le code de quelqu’un d’autre. On disait parfois en riant : « ça a été difficile à écrire, ça doit être difficile à lire », en réalité, c’est une blague, faut pas le faire.
  • La partie marketing qui peut ainsi affirmer que la fonctionnalité existe et qu’il est possible de s’en servir

Quand vous voyez la Documentation comme une punition, en réalisé, vous punissez les personnes que je cite dans ma courte liste. Et quand j’évoque la Documentation, cela ne se limite pas aux pages écrites dans un bon anglais/français, avec des jolis exemples théoriques de code. Cela inclut les bons messages d’erreurs, les informations retournées par l’API, et les commentaires dans le code, ainsi que les diagrammes concernant l’architecture et le pourquoi de ces choix.

Le CommitStrip m’y a refait penser au point que je me suis dit que j’allais écrire un billet sur le sujet : http://www.commitstrip.com/fr/2016/07/27/documentation-just-before-vacation/

Il est temps de réfléchir et mûrir un peu sur ce sujet, ne croyez-vous pas ?

 

Ajouter mes idées

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s