Il faut documenter : j'y reviens !

La question de la documentation est bien connue des informaticiens, qui enchaînent des lignes de programme et qui arrivent à des programmes énormes... Comment y dépister des erreurs ? Comment les modifier ultérieurement ? Quand c'est programmes ne sont ni structurés ni expliqués, c'est impossible.

Et c'est la raison pour laquelle on n'insiste jamais assez :  il faut documenter.

D'ailleurs, cette documentation n'est pas pour seulement pour les autres, mais pour soi-même, et c'est la raison pour laquelle on doit d'abord penser à un organigramme, qui consigne en français ce qui sera codé.

Puis il faudra entrer dans le détail, et indiquer par des phrases en français (des "commentaires") ce que font les opérations que l'on met en oeuvre.

Ce qui vaut pour l'informatique vaut évidemment pour le calcul algébrique, le calcul matriciel, tous les calculs en réalité.
Et insistons : il ne s'agit pas seulement de faire cela pour les autres, mais pour soi-même !

J'ai encore vu hier l'exemple de feuilles de calcul de certains amis qui enchaînaient les opérations sans aucune phrase en français... et qui étaient perdus.

Evidemment, quand ils m'ont soumis le problème qu'ils ne parvenaient pas à résoudre seuls (puisqu'ils étaient perdus), je n'y suis pas arrivé, parce que même eux ne savaient pas dire ce qu'ils avaient fait.

Il y a un point encore supplémentaire à donne,  qui est que le calcul algébrique notamment est fondé sur la pensée en langage naturel  : on n'a pas assez répété que les équations ne sont que des expressions d'idées en langage forme. Une équation correspond à une idée en langage naturel.

Bien sûr, il y a quelques génies qui  calculent comme chantent les rossignols, qui n'ont plus besoin de cette traduction, mais avant d'être un génie, il y a lieu d'apprendre à le devenir, et le seul fait que les jeunes qui apprennent fassent des erreurs montre qu'ils n'ont pas encore atteint cet état. Ils doivent donc apprendre tranquillement, et cela passe par de la documentation... qui ne doit pas se faire à posteriori, mais a priori !

Car on conservera aussi cette idée que nous devons avoir des objectifs clairs sans quoi nous ne pourrons pas trouver les chemins qui y mènent.

Oui, quand on fait un calcul il y a un objectif et on ne se lance pas au hasard vers cet objectif, mais selon un chemin qui doit avoir été prédéterminé.

Autrement dit, il faut dire en français quel est l'objectif, puis soliloquer (par écrit !) pour analyser le chemin, les étapes. Et soliloquer encore pour dire comment on parcourera les petits segments du chemin entre les étapes.

Et c'est alors amusant : souvent, ayant ainsi écrit en français, la traduction mathématique ou informatique devient évidente !

Une bonne pratique en science : documenter les calculs

Documenter les calculs  : le monde informatique connaît bien la chose, après le monde mathématique ; un calcul est une écriture qui se double de l'idée en français.
Commençons par les mathématiques, avant de passer à l'informatique, puis d'arriver à la recherche scientifique en général.

Pour les mathématiques, j'ai vu d'innombrables collégiens et lycéens qui s'étonnaient de ce que leurs devoirs soient mal notés. Ils n'avaient pas compris, ou on ne leur avait pas dit (je ne tranche pas, entre les deux parties), que des calculs se font en français, avant que le formalisme ne vienne recouvrir les mots. Cela, c'est pour le chemin, mais, surtout, ils étaient censés expliquer ce qu'ils faisaient, et pourquoi ils le faisaient, au lieu de simplement faire... avec plus ou moins de succès.
Le pire, c'est la question des proportions, et du détestable "produit en croix", que font les étudiants jusqu'au master, en se trompant une fois sur deux : je répète que j'ai sur mon mur de bureau une proportion simple faite par deux étudiants de master différents... et qui sont deux résultats différents. L'un est faux, bien sûr, mais, surtout, aucun des deux étudiants n'étaient prêt à parier une bouteille de champagne que son résultat était juste.
Cette observation n'est pas une critique de quiconque, mais une observation factuelle, et, plus précisément, une observation du fait que nous ne disons pas assez aux écoliers, collégiens, lycéens, puis étudiants, et enfin nous-mêmes, que les calculs se font (sauf pour quelques génies) en langue française, avant que le formalisme ne soit présent. C'est la garantie d'une lisibilité pour les autres (on rappelle qu'un devoir est aussi destiné au professeur qui l'évalue)... et surtout pour soi-même : car pour s'assurer que l'on a fait un calcul juste, il faut pouvoir se relire et se comprendre.

Pour l'informatique, la question est identique, mais plus récente. Et les sociétés qui produisent du code connaissent la plaie des programmes mal documentés, que personne ne parvient plus à modifier quelque temps après qu'ils ont été produits. C'est que, là encore, il est très difficile de refaire le chemin quand il est caché sous le code, et même avec des langages qui semblent plus intuitif, il est essentiel de "documenter". Pour soi et pour les autres, comme précédemment. Je n'insiste pas beaucoup, car il y a en ligne  des milliers de pages consacrées à ce problème.

Arrivons donc enfin à la question de la recherche scientifique. Pour les sciences de la nature, il y a donc des calculs, plutôt que des mathématiques. J'explique la nuance : les mathématiques visent le développement des mathématiques, alors que le calcul est du calcul, appliqué à des questions pratiques.
Bref, il y a du calcul, et, de ce fait, ce calcul doit être documenté. Rien de pire que ces documents de recherche que, là encore, personne ne parvient à décoder quelques mois après qu'on les a produits. Le pire, c'est que leurs auteurs eux-mêmes ont bien du mal à s'y retrouver.
 Or la science est produite par des scientifiques qui, le plus souvent, sont des agents de l'Etat. Il n'est donc pas normal qu'elle ne puisse être mise à disposition du public. D'autre part, elle se fait souvent dans des groupes de recherche, de sorte que la communication entre membres du groupe est essentielle : là, c'est une question non plus de citoyenneté, mais d'amitié.
Surtout, il y a le fait, souvent négligé, qu'il est essentiel de se parler à soi-même. Se relire après quelques mois, par exemple. Sans une bonne documentation des calculs, on est condamné à perdre son travail, ou à perdre du temps à retrouver les idées qu'on avait eues.

Bref, je crois que c'est une bonne pratique que de bien documenter les calculs !