Le README manquant

The missing semester

En 2020 trois profs du MIT donnent un cours d’informatique nommé The Missing Semester¹. La motivation derrière ce cours est la suivante :

Classes teach you all about advanced topics within CS, from operating systems to machine learning, but there’s one critical subject that’s rarely covered, and is instead left to students to figure out on their own: proficiency with their tools. We’ll teach you how to master the command-line, use a powerful text editor, use fancy features of version control systems, and much more!

Students spend hundreds of hours using these tools over the course of their education (and thousands over their career), so it makes sense to make the experience as fluid and frictionless as possible. Mastering these tools not only enables you to spend less time on figuring out how to bend your tools to your will, but it also lets you solve problems that would previously seem impossibly complex.

Au programme, entre autres :

• Le shell
• Les éditeurs de texte (VIM)
• Les CLI
• GIT
• Les outils de debug
• La compilation, l’intégration continue
• Markdown
• Les VPN
• Les backups
• etc

Une bonne partie de ces sujets sont parmis ceux que l’on considère traditionnellement à Katzele comme étant des bases importantes de la pratique de l’informatique. Comme le corps enseignant le précise, maîtriser ces outils peuvent transformer des problèmes très complexes en problèmes bien plus simples. Utiliser ces outils comme briques pour en créer un nouveau et considérer leur connaissance, même basique, comme un prérequis à son bon usage permet de prendre énormément de raccourcis dans son développement.

En prenant protocolium on peut par exemple citer :

• la compilation avec make en ligne de commande, permettant de ne pas coder et maintenir de logique de dépendances spécifiques au projet et permettant en quelques lignes de proposer des “commandes` pour lancer/arrêter le serveur de test etc.
• le stockage du contenu dans des fichiers texte, leur catégorisation par arboresence de dossiers et l’édition en local via un éditeur de texte quelconque. Permet de ne pas avoir à créer/maintenir une interface web d’édition de protocoles avec possible authentification,
• délégation de l’authentification à SSH pour le déploiement sur le serveur et les dépôts git, permettant de ne pas avoir à gérer de secrets dans l’outil.
• versionnage via git, décorrélé du bon fonctionnement de l’outil, permis par l’utilisation de fichiers texte. Permet de ne pas avoir à gérer des versions dans l’outil directement.

Ces choix impliquent tous une plus grande simplicité technique de l’outil puisqu’il se décharge d’un ensemble de fonctionnalités sur d’autres outils. La plupart de ces fonctionnalités peuvent être reproduites à l’échelle de l’utilisateurice, pour peu qu’iel sache efficacement se servir des outils de son système. Exemple : dans protocolium les protocoles sont déclarés comme une suite de fichier d’étapes, identifiés par les chemins :

etapes:
documentation/etapes/etape1.sh
documentation/etapes/etape2.sh
documentation/etapes/etape3.sh

Si l’on souhaite éditer ce protocole il pourrait être agréable d’ouvrir rapidement toutes les étapes dans son éditeur de texte. Cette opération sera fastidieuse pour une personne étant peu à l’aise avec la navigation dans son arborescence de fichier et/ou ne sachant pas comment interfacer la recherche de son explorateur de fichier avec son éditeur de texte. A l’inverse, une personne ayant les compétences dispensées dans le Missing Semester aura peut-être pour réflexe de se créer un rapide outil :

< fichier_protocole sed 1d | xargs $EDITOR

ouvrant automatiquement les étapes. Alternativement certains éditeurs de texte on des raccourcis par défaut permettant l’ouverture d’un fichier si l’on place le curseur sur son chemin. On pourrait également citer l’usage de messages d’erreurs au format fichier:ligne:colonne: message d'erreur, standard dans les compilateurs C par exemple, permettant très facilement de naviguer directement au bon endroit dans le bon fichier dans les éditeurs de texte compatibles².

Ces fonctionnalités relèvent du confort³ mais d’autres besoins représentent de vrais obstacles. Si le versionnage est fait via git il faudra nécessairement apprendre un minimum de git. Quoi qu’il en soit on en arrive à une conclusion : pour que l’utilisation d’un outil prenant des raccourcis sur la base d’un usage relativement aisé de l’écosystème Unix soit un succès il faut former les utilisateurices. En plus du README expliquant l’usage de l’outil il manque une explication de l’environnement dans lequel la personne sera emmenée à évoluer. Il manque un README.

Le README manquant

L’utilisatrice principale de protocolium maintient, depuis le premier jour ou presque, un fichier compilant tutoriels, astuces et liens de références à propos des outils autour de protocolium. Commandes git, options de make, oneliner shells pour faire des substitutions de masse, rappels de syntaxe markdown, tutoriels pour modifier les raccourcis des éditeurs de texte, tout y passe.

On pourrait dire que ce fichier documente pour protocolium ce que le Missing Semester documente pour la formation en informatique au MIT : tous les présupposés et para-compétences nécessaires à l’utilisation effective de l’outil. Il donne à voir ce que coûte la “simplicité” technique de protocolium.

Il pourrait être intéressant de l’intégrer à la documentation “officielle” de protocolium ou d’en faire le germe d’une formation à protocolium. Plus que le simple usage de l’outil, qui en réalité peut se résumer en une dizaine de paragraphes, une bonne formation à protocolium serait une formation à Unix + un peu de make + un peu de shell + markdown + un peu d’HTML + un éditeur de texte capable. L’étendue des compétences est conséquente mais :

1. Il n’est pas nécessaire d’être expert·e en shell en make ou en markdown, simplement de connaître les bases
2. Toutes ces compétences peuvent être utiles dans de très nombreux autres contexte. Par exemple à Commown :
   • Connaître des bases d’Unix est utile puisque tout le monde est sous Linux
   • Connaître des bases de shell est utile puisque l’équipe IT ne rechigne pas à faire utiliser le terminal aux collègues quand c’est plus rapide/pratique et que le support résout de nombreux soucis des clients en leur faisant exécuter des commandes
   • Connaître des bases de markdown est utile pour la prise de note en réunion et la rédaction de documents. L’instance Nextcloud utilisée dans l’entreprise propose un éditeur de markdown

Les fonctions de protocolium sont fermement situées à Commown⁴ mais les compétences nécessaires à son utilisation sont davantages situées dans l’espace vers lequel j’aimerais emmener les collègues, celui où nous⁵ sommes en capacité de produire du logiciel simple. Je me suis permis ce pari puisque la personne manipulant protocolium est ingénieure, à l’aise techniquement et enthousiaste à l’idée de se former.

Cela dit, en attendant qu’elle prenne ses aises dans l’espace de compétence propice à l’utilisation de protocolium j’ai construit un ensemble d’outils non essentiels pour l’assister que l’on pourrait nommer “para-outillage”.

Le para-outillage

Bien que protocolium n’intègre pas de nombreuses fonctionnalités en dehors de son cœur il propose optionnellement des commandes et “méta-commandes” qui permettent d’effectuer les opérations de manipulation de texte nécessaires à l’édition des protocoles. Par exemple bin/helpers/ajouter-etapes-proto permet d’ajouter une étape à un protocole :

$ bin/helpers/ajouter-etapes-proto documentation/protocoles/blabla.sh
documentation/etapes/blabla.sh
Etapes documentation/etapes/blabla.sh ajoutées au protocole
documentation/protocoles/blabla.sh avec succès

Qui au fond ne fait pas grand chose d’autre qu’un echo "$etape" >> "$protocole" après avoir vérifié si les arguments existent. La méta-commande bin/ed-proto quant à elle permet d’exécuter ces commandes après avoir sélectionné les protocoles et étapes sur lesquels on veut opérer via des menus interactifs. Elle affiche également les commandes exécutées de manière à rendre visible son simple rôle d’orchestratice et de faciliter l’automatisation personnelle à coup de copié/collé.

Ce compromis permet de sauter largement le prérequis “Usage avancé d’un éditeur de texte/IDE” au prix de quelques centaines de lignes de code à peu près raisonnables à maintenir. Ce “para-outillage” est par définition non essentiel. L’édition des protocoles n’est que de l’édition de fichiers texte, il sera toujours possible de le faire “à la main”. Si demain cet outillage se révèlait trop bugué ou trop peu pratique protocolium continuerait de fonctionner. Le fait qu’il soit non-essentiel implique également qu’il ne s’impose pas aux personnes parvenant à efficacement faire de l’édition avec leur propre outillage. En revanche s’il se révèle excessivement utile pour la plupart des utilisateurices il risque de devenir essentiel de fait et donc freiner freiner l’acquisition de certaines compétences transverses évoquées au précédent titre. Il est donc probablement utile pour la maitrise de la complexité de l’outillage sur le long terme que la para-outillage reste convivial et donc :

1. d’éviter de rendre le format de donnée trop complexe et donc le para-outillage par la même occasion
2. de continuer à se former sur ces fameuses compétences “manquantes” pour ne pas dépendre du para-outillage
3. d’éviter de rendre le para-outillage trop pratique/puissant et donc trop essentiel

Si protocolium devait être uniquement utilisé par des personnes très à l’aise avec le monde Unix et les outils évoqués dans cet article c’est plus de 400 lignes de para-outillage et entre 15 et 20 lignes de gestion d’erreur dans le coeur de l’outil qui pourraient être purement et simplement supprimées.