Aller au contenu

README, un fichier nommé plaisir

Par Thomas Parisot

Mini-conf (15 mn) :
Langue :
Français
CC
  • Diaporama
  • Liens connexes

    Le sujet

    Vendredi, mise en production. Vous annoncez à vos proches que pour l'apéro ce soir, c'est mort, vous êtes dé-bor-dé(e).

    Un mauvais clic plus tard, le site est mort. Ambiance fin du monde pendant que vos amis s'amusent.

    Si vous aviez su que la rédaction du README de votre projet vous aurait permis non seulement de préserver votre apéro sacré, mais en plus de livrer le cœur léger, vous l'auriez sûrement écrit plus tôt.

    Avant que le monde ne s'effondre sur lui-même, nous ferons encore mieux : 15 minutes c'est juste ce qu'il faut pour créer un code robuste.

    Présenté par

    Transcription

    (Merci à Tanguy Lohéac pour la transcription.)

    C’est bon ? OK.
    Bonjour à tous.
    Je me permets du vendredi pour faire un petit troll, histoire de commencer la conférence.
    C’est bien évidemment une fausse citation, puisque la vraie est de Georges Orwell.
    C’est un écrivain plutôt fantastique et qui a écrit notamment « 5 conseils sur la simplicité pour écrire ».
    Et je me suis dit que ça serait quelque chose d’assez sympathique de faire quelque chose de plus simple.
    Et c’est exactement pour ça en fait que je vais vous parler d’un fichier qui est tout bête et qu’on a souvent oublié ou qu’on zappe, ou ce genre de choses,
    Et dont je me suis servi pendant 1 an avec mon équipe pour démarrer les projets et faire en sorte que tout soit plus simple.

    Dans readme, il y a « me » donc je vais vous parler tout rapidement un petit peu de moi.
    Je profite de Paris Web pour vous passer quelques albums photos des dernières vacances. [rires]
    Mais même si les paysages sont jolis, c’est un pays…
    Donc l’Islande est un pays qui est assez rude.
    On en a un petit peu parlé hier.
    Mais ce qui fait que les gens ont changé leur constitution, c’est surtout le fait, pas qu’ils soient peu nombreux, mais le fait que les gens se sentent rapprochés par la difficulté de l’environnement.
    Et un Islandais m’a très bien dit sur place que :
    Le monde est compliqué, la vie est compliquée, donc on aime les choses simples. Alors faisons des choses simples.
    Donc on fait des choses simples. Et c’est assez formateur.
    Donc voilà. Donc je suis essentiellement développeur web expérimenté.
    Avant je disais « consultant » mais j’aime plus trop ce mot.
    Je préfère dire que je sais faire les choses, plutôt que de dire : on va faire d
    Les choses.

    Donc, faisons ! Faisons, c’est bien.

    J’ai expérimenté NodeJS pendant plus d’une année.
    Et pour l’instant j’ai pas encore de cancer.
    Donc c’est plutôt pas mal.
    Javascript côté serveur c’est assez sympathique, et côté front aussi, et même dans le navigateur.
    Parce qu’aujourd’hui ce qui est pratique c’est qu’avec un seul langage, ben on peut tout faire.
    Et avec HTML et CSS on fait encore plus de choses.
    Ce qu’il y a même 10 ans ou 15 ans était quelque chose d’impensable.
    Il fallait faire du java, du websphere et compagnies.
    Aujourd’hui avec des petits langages modulaires, fonctionnels, et bien on arrive à faire des choses.
    Ben si en 12 mois on a cramé tout le cash de la startup qu’on avait créée, et ça a abouti dans des situations qui sont assez dramatiques, donc je vous invite à ne pas prendre les choses à la légère, et à rester positif.
    Parce qu’au final, même si ça s’est passé pas forcément très bien, on a créé une équipe qui était super, qui est soudée et avec qui on a réussi à faire des choses très bien, essayer des choses nouvelles sans forcément que ça pose de souci. Et voilà ! On est… la solidarité des gens dans ces genre de moments est assez sympa.

    Je reviens également 1 an en arrière, puisqu’on a fait un atelier marshmallow challenge qui s’est quand même superbement soldé par la plus haute tour en spaghetti quand même du tout Paris Web. [rires]
    Et on n’en est pas peu fier.
    Mais ce qui était très important, je pense, dans cet atelier, c’est ce côté où… ce que ça a vraiment permis de révéler c’est…
    On a été habitué jusqu’à présent à écrire des cahiers des charges hyper lourds, hyper compliqués.
    Et finalement on s’est rendu compte qu’on aboutissait à une meilleure qualité dans l’achèvement et dans la réalisation des choses, ben juste parce qu’on a discuté, parlé, sans forcément qu’on ait l’habitude de discuter ensemble.

    Donc du coup, je me suis dit :
    Ben pour travailler avec des gens, en fait on va arrêter d’écrire, on va plutôt parler.
    Et c’est… dialoguer c’est vraiment...
    C’est pas juste dire : tu vas faire quelque chose et j’écoute pas ta complainte.
    Mais on va faire effectivement du…
    On va parler ensemble, je vais t’écouter et on va itérer de cette façon là pour aboutir et construire quelque chose.
    C’est vraiment ça le dialogue. C’est pas juste : j’t’écoute et je fais ce que j’ai envie de faire.
    Donc pour travailler ensemble, il y a des choses qu’on voulait vraiment pas faire.
    Ben on voulait pas écrire de spec.
    Parce que franchement on trouve ça chiant : écrire 40, 50, 60, 70 pages de spec pour écrire, pour faire un produit.
    Que ce soit une startup, que ce soit autre chose, c’est quand même pas très très agréable.
    Et on voulait encore moins faire de spec parce qu’il faut les maintenir après.
    Et c’est un truc qu’on oublie souvent.
    C’est que dans les projets on doit écrire une spec mais, le monde est ce qu’il est, les choses changent, les choses bougent, et personne n’a envie de maintenir les specs.
    Enfin en tout cas des cahiers des charges bien compliqués, support HTML et tout ça, il en faut. Mais il y a des équipes qui sont payées pour ça.

    Mais par contre, il y a d’autres choses qu’on voulait.
    Et on voulait, pas se faire des bisous, mais on voulait faire des choses simples.
    On avait une personne qui était en télétravail et 3 personnes sur place.
    Et on travaillait pas forcément tous sur les mêmes projets.
    Mais bon, globalement, on n’avait pas envie de se prendre la tête à faire des choses qu’on n’avait pas envie de faire.
    Donc on a fait ça.
    Donc du coup en fait on s’est concentré sur un fichier pour commencer les projets.

    C’est-à-dire un fichier readme.
    C’est un fichier qu’on trouve généralement depuis très longtemps en informatique, à la racine de vos projets, de vos sources que vous téléchargez ou que vous dézippez.
    Souvent vous le regardez pas.
    Mais peut-être que certains ont l’habitude de regarder ce fichier en premier quand il leur arrive un pépin, quand ils savent pas comment l’installer, quand ils savent pas quoi faire, ben ils vont jeter un œil dedans.
    Donc on s’est dit : ben tiens.
    Au lieu de faire tout ce que j’ai décrit jusqu’à présent, si on faisait juste ça en fait ?
    Juste un fichier… juste un fichier tout simple.
    Donc, ce qui est important c’est de se dire : à quoi ça sert.
    Dans ce fichier-là on se dit : là globalement le projet qu’on est en train de démarrer et dont on est en train d’écrire le code, ben franchement il sert à quoi ?
    Et ça paraît bête, mais juste sur le premier paragraphe, être au clair sur ce que ça fait, ben ça résout pas mal de choses.
    Puisque déjà, à 4, on pouvait dire… on pouvait très bien avoir des divergences sur la philosophie du projet, ou plutôt, imaginer qu’une partie du code serait en fait dans une autre application.
    Et ça permettait déjà de se concentrer à la base sur le métier, et de focaliser sur le métier d’application.
    On a un métier, mais chaque application a également un métier.

    Surtout dedans, ce qui est très important c’est de dire : ben comment en fait, le projet qu’on est en train de faire, comment on l’installe,
    Comment on le met à jour, comment on développe dessus, comment on le déploie, comment en fait, comment on s’en sert, c’est vraiment le B A BA.
    C’est le mode d’emploi version simplifiée.
    C’est : je suis… je connais pas le projet, je lis ce fichier.
    Comment je fais en fait pour m’en sortir avec ce truc-là ?
    Surtout si il y a un pote qui a fait la mise en prod, il est en vacances.
    Mais faut que je me mette dedans hyper rapidement, Je vais pas me palucher un ensemble de 40 pages pour arriverà comprendre qu’en fait il fallait changer juste une virgule à un endroit.
    Et surtout, comment ça s’utilise, parce que c’est bien de développer, mais on est également les utilisateurs de notre propre code.
    Et quand on est dans une entreprise, ben vos collègues en fait sont les utilisateurs de ce que vous avez créé, ou en tout cas vous participez.
    Donc c’est important de pouvoir expliquer aux gens comment, comment on fait marcher ce que vous avez créé ou ce qui a été créé en équipe pour, ben juste, simplement vous en sortir en décrivant comment fonctionnent les APIs, en mettant différents exemples, et puis, éventuellement, en faisant des renvois vers d’autres fichiers si jamais il y a nécessité de faire quelque chose de beaucoup plus détaillé et exhaustif.
    Ben globalement ça a quand même aussi plutôt bien marché.
    C’est-à-dire qu’on a fait quelque chose dont on savait pas trop à quoi ça aboutirait.

    Et ça a plutôt bien marché.
    Pourquoi ?
    Parce qu’on se servait de Github déjà à la base.
    On voulait pas trop se prendre la tête et installer nous-mêmes ce qu’il fallait.
    Donc, on s’est dit : on prend sur Github.
    Et il se trouve que ben, en fait sur Github, c’est quand même un des premiers trucs qu’on voit.
    Ils incitent même d’ailleurs aujourd’hui à créer automatiquement le fichier, à le préremplir avec des informations de base.
    C’est bien, c’est cool, ça permet de gagner du temps.
    Et nous, ça nous permettait d’utiliser un outil déjà existant en le mettant à profit pour faire… pour mettre en place ce système-là.
    C’est également le premier fichier qu’on voit sous son nez.
    Donc, ben, tant qu’à faire, en plus, on n’a pas grand-chose à configurer.
    C’est vraiment… ça tombe sous le nez.
    Et il faut vraiment mettre de la mauvaise volonté pour pas tomber dessus.

    Et ça permet de voir, comme je l’expliquais tout à l’heure, à quoi ça sert, que ben en fait, les tests passent hein. Parce que c’est aussi bien pour faire des tests. Et surtout à ça sert, les principaux intérêts.
    Et vu que c’est facilement visible et que ça vous tombe sous le nez, ben c’est également plus facile de le maintenir à jour, parce que ben vous vous en apercevez vite et si vous le mettez pas à jour ça peut aussi vite vous retomber sur la tronche.
    Parce que votre pote il va vous dire : mais je comprends pas. J’ai lu ta doc, c’est pas à jour.
    Il y a pas grand-chose.
    Ça coûte moins de temps également à mettre à jour, surtout s’il y a une petite différence.
    Et encore plus quand on a un éditeur qui est directement en ligne, où on peut pas dire : non mais je suis obligé de récupérer tout le code, tu comprends, c’était lourd !
    Ça se fait en ligne, c’est vite fait, et c’est très simple.

    Un truc qui est bien aussi c’est qu’il y a aucun apprentissage.
    Savoir écrire, a priori en étant développeur, on s’en sort plutôt pas mal.
    Même si on n’écrit pas un anglais parfait, même si on n’écrit pas un français parfait, ben le but c’est d’écrire quelque chose qui est lisible et compréhensible.
    Taper sur votre clavier, vous savez faire.
    Donc il y a pas un langage de plus à apprendre.
    Vous utilisez ce que vous voulez.
    Github prend la Markdown par défaut.
    Il utilise plein d’autres langages.
    Vous voulez juste faire des fichiers textes avec des retours à la ligne et des tirets, ça marche tout aussi bien.
    Voilà il y a rien de plus à apprendre.
    C’est également très simple, puisque côté syntaxe, des crochets, des étoiles, des dièse, pour juste faciliter un petit peu la mise en forme, ça coûte pas très cher.
    Du coup c’est rapide à écrire, puisque vous avez pas toute la mise en forme HTML à faire.
    Vous avez pas Word qui vous pète dans les doigts.
    Vous allez pas pester contre Open-Office parce qu’il a décidé de vous faire foirer la sauvegarde.
    Donc vous gagnez du temps aussi à rédiger ce qui vous est utile dans un projet.
    C’est pas mal.

    Et en plus, ce qui est pratique, c’est que comme c’est court, ben ça se lit assez rapidement.
    Donc vous pouvez en discuter également plus facilement.
    Et s’il y a des erreurs, vous les voyez également plus facilement.
    C’est un peu comme de l’agile pour de l’écrit, en fait.
    On se plante plus facilement et on corrige plus rapidement.
    Et après, ça permet de tester aussi un petit peu ce que vous allez faire, sans écrire de code, et sans tester.
    Enfin vous allez écrire un petit peu de code, vous allez le mettre dans votre fichier readme.
    Donc vous commencez déjà à designer un petit peu l’API en disant :
    Ben tiens, cette librairie, en français ça fait, et en code ça se traduit de cette façon.
    Vous pouvez voilà, marquer que vous attendez a priori tel ou tel résultat sur l’utilisation, qu’il y a des cas un petit peu particuliers.
    Mais surtout, ce qui est bien c’est que, quand vous en discutez ensuite avec vos collègues ils vont vous dire : ah non mais ça c’est pas bon !
    Mais sauf que ça vous coûte rien à rectifier puisque vous avez même pas encore écrit le code.
    Et ça c’est pas mal.
    Et surtout ça permet d’améliorer la testabilité, parce que ben moi, au début par exemple, il y a longtemps j’avais peur d’écrire des tests.
    Parce que pour moi les tests c’était houf…
    Je comprenais l’utilité mais ça me faisait un peu peur.
    Sauf que, en faisant ça, en commençant pas écrire déjà l’API, ben vous écrivez en fait déjà un petit peu les tests.
    Et derrière, à écrire c’est assez simple.
    Puisque ce que vous avez écrit dans le readme, c’est globalement ce qu’il faut aller tester derrière.
    Donc, vous voulez tester, vous testez pas, vous faites ce que vous voulez.
    Mais au moins ça vous permet d’embrayer dans un rail qui vous permettra de faire les tests maintenant ou de les commencer de suite.
    Parce que, après, vous pouvez faire de TDD, du BDD, du ce que vous voulez DD, c’est pas un souci.
    Vous êtes pas obligé de tester derrière, mais au moins, vous rentrez dans ce rail qui peut-être, un moment donné, vous permettra de rentrer dedans.
    Et en fait, il se trouve qu’en cherchant un petit peu, il y a une personne qui avait parlé un petit peu de ce principe-là il y a 2 ans.
    Donc, j’ai pas réinventé la roue non plus.
    Mais après coup, je me suis rendu compte que ça avait été fait et que, lui, voilà, c’était exactement le même principe : Passons moins de temps à écrire des choses compliquées !
    Passons… voilà passons un peu de temps à faire des choses simples, pour rendre tout simple pour les gens !

    Et bon, certains après ont même poussé en allant plus loin, à créer un framework de tests basé sur le readme.
    Donc, vous écrivez votre readme et ça vous joue tous les tests unitaires dans la foulée…
    J’irais pas jusque là parce que ça rend les choses un peu plus complexes.
    Mais voilà… donc bref…

    Faites simple ! Faites Islandais quoi !
    Voilà.
    [Applaudissements]