Qu'est-ce qu'un bon fichier Lisez-moi.txt

Vous venez de finir votre outil sur lequel vous tra­vaillez depuis 1 semaine/​1 mois/​1 an/​10 ans (rayez la men­tion inutile) qui va révo­lu­tion­ner votre domaine.

Votre code est ver­sion­né, for­ma­té, com­men­té, docu­men­té, tes­té, les résul­tats sont éva­lués selon le gold stan­dard de la dis­ci­pline sur des jeux de don­nées repré­sen­ta­tifs de la réa­li­té, votre publi­ca­tion est prête, vous allez l'envoyer sur le dépôt de pre­print et au jour­nal, le thread Twit­ter d'annonce est rédi­gé. Mais là pata­tras vous vous ren­dez compte que vous avez oublié de rédi­ger le Readme qui va accom­pa­gner votre code.

Retour aux sources

Le fichier Readme ou Lisez-moi est géné­ra­le­ment un fichier qu'on trouve à la racine d'une arbo­res­cence de dos­siers. Il donne des infor­ma­tions sur ces fichiers, des ins­truc­tions d’installation, d'utilisation, des infor­ma­tions sur les auteurs, la licence d'utilisation asso­ciée au fichier. Si vous traî­nez dans les FTP de l'EBI ou du NCBI vous devriez voir des Readme qui décrivent le conte­nu des dos­siers.

C'est donc tout natu­rel­le­ment que Github a déci­dé d'afficher le conte­nu de ce fichier Readme quand il est pré­sent à la racine d'un dos­sier et que de nom­breuses autres forges logi­cielles appliquent aus­si cette idée. Ce fichier Readme est un peu deve­nu la page d’accueil de votre pro­jet, il faut donc faire par­ti­cu­liè­re­ment atten­tion à son écri­ture. Dans ce billet, je vais pré­sen­ter les dif­fé­rentes sec­tions qui me semblent inté­res­santes d'intégrer dans un Readme pour en faire un bon Lisez-moi.

ATTENTION : L'objectif de cet article n'est abso­lu­ment pas d'être nor­ma­tif, vous faites bien ce que vous vou­lez : ne vous cen­su­rez pas à cause de ce billet de blog. Je ne fais que décrire les points que j'aime bien retrou­ver dans un Readme.

Le titre

Concer­nant le titre j'ai lis­té ces dif­fé­rentes grandes méthodes :

• le nom de l’outil ;
• l'explicitation de l’acronyme qui donne le nom de l’outil ;
• le nom de l’outil avec l'explicitation de l’acronyme ;
• le logo de l’outil ;
• le logo de l’outil avec le nom à côté ;
• le logo de l'outil avec le nom de l’outil dans une jolie image.

Je n’ai pas vrai­ment de recom­man­da­tions sur quelle méthode choi­sir glo­ba­le­ment, c'est selon votre sen­si­bi­li­té artis­tique et votre temps. Mais si vous choi­sis­sez une des options logo, faites atten­tion à bien mettre un texte alter­na­tif (l'accessibilité c'est impor­tant), et à ce que l'image ne soit pas trop sur­char­gée. Éga­le­ment, pen­sez à deman­der des avis externes avant de rendre l'image publique pour être sûr qu'elle soit bien lisible et que le mes­sage de votre image passe bien. Si vous vou­lez une touche de cou­leur sans trop vous embê­ter vous pou­vez uti­li­ser des émo­jis, 💻 🧬 par exemple.

Pour résu­mer il vous faut un titre mais n'y pas­sez pas trop de temps si vous n'y tenez pas abso­lu­ment.

Les badges

Vous avez dû voir ces petits badges infor­ma­tifs dans les Readme de nom­breux dépôts, pour indi­quer la licence logi­cielle, si la ver­sion actuelle a pas­sé les tests, le taux de cou­ver­ture de ces tests, la dis­po­ni­bi­li­té dans dif­fé­rents dépôts logi­ciel, l’existence d'une docu­men­ta­tion, le nombre de fois qu'il a été télé­char­gé.

Si vous aimez mettre des badges allez‑y, si vous n'en sen­tez pas la néces­si­té ne vous for­cez pas.

La description

Rajou­tez une des­crip­tion pour indi­quer l'objectif de votre outil, com­ment il fonc­tionne, ce qui le dif­fé­ren­cie des autres outils simi­laires, pour­quoi vous l'avez créé. Il faut que le lec­teur du domaine puisse com­prendre rapi­de­ment pour­quoi vous avez créé cet outil. Si des gens se passent le lien de votre dépôt, ils n'auront pas for­cé­ment pris la peine de décrire l’outil cor­rec­te­ment.

Ne faites pas trop long non plus, un para­graphe maxi­mum avec éven­tuel­le­ment une image. Vous avez nor­ma­le­ment four­ni une docu­men­ta­tion ou un manuel pour per­mettre d'aller plus loin. N’hésitez pas à don­ner le lien vers ces docu­ments d'ailleurs.

L’installation

On arrive sur un gros mor­ceau. Votre pro­cé­dure d’installation doit être la plus simple pos­sible. Si quelqu'un doit télé­char­ger l'intégralité d'internet, apprendre le polo­nais et sacri­fier une chèvre en réci­tant de l'araméen pour tes­ter votre outil, même si votre outils per­met de conver­tir un fichier fastq en publi­ca­tion scien­ti­fique, il ne le fera jamais.

Ten­tez de four­nir des pro­cé­dures d’installation uti­li­sant des sys­tèmes de package, deb, rpm, conda, home­brew, et vous pou­vez même four­nir une image docker. Plus la méthode sera simple mais sur­tout consen­suelle au sein de votre com­mu­nau­té, mieux ce sera.

Si vous consi­dé­rez, et c'est votre droit, que ce n'est pas votre tra­vail de four­nir des paquets, il est impor­tant de four­nir une liste de toutes les dépen­dances et de leurs ver­sions (avec un lien, c’est mieux), et la liste des com­mandes néces­saires à l’installation de l’outil. S’il y a beau­coup de com­mandes, vous pou­vez les cacher dans un script ou un make­file. Je vous recom­mande tous de même d'indiquer que vous pou­vez aider les packa­geurs à créer des paquets et les invi­ter à vous contac­ter.

Par ailleurs, il est tou­jours plus agréable pour l'utilisateur d'avoir une pro­cé­dure d’installation qui ne demande pas les droits admi­nis­tra­teur et qui ne va pas pla­cer des fichiers par­tout (ou alors four­nis­sez un script de dés­ins­tal­la­tion qui fonc­tionne). Pour être sûr que tous se passe bien, tes­tez votre pro­cé­dure dans un docker, une VM vierge, voire faites tes­ter par une per­sonne exté­rieure au pro­jet sur un autre sys­tème d'exploitation que le vôtre.

Je vais conclure là-des­sus et l'écrire en gras car c'est très impor­tant, un outil facile à ins­tal­ler est un outil uti­li­sé donc un outil cité !

L'utilisation

Don­nez des exemples de com­ment uti­li­ser votre logi­ciel, les entrées, les sor­ties, les para­mètres impor­tants, les valeurs de para­mètres recom­man­dées dans dif­fé­rentes situa­tions. Si jamais vous avez créé un tuto­riel plus com­plet pour une pre­mière uti­li­sa­tion de votre outil, n'hésitez pas à l'indiquer ici éga­le­ment.

Il faut évi­ter de ren­trer trop dans les détails, on est pas dans un manuel uti­li­sa­teur, mais si vous en avez un pen­sez à rajou­ter un lien.

How to cite

Géné­ra­le­ment une sec­tion qu'on retrouve à la fin mais qui reste très impor­tante com­ment citer votre outil. Ici il y a beau­coup de for­mat dif­fé­rent (Mend­ley, bibi­tex, zote­ro), un liens vers la publi­ca­tion est un mini­mum.

Conclusion

Voi­ci à peu près les sec­tions que je m'attends à trou­ver dans un Readme, et que je trouve géné­ra­le­ment. Bien évi­de­ment, on peut varier autour de ces idées, rajou­ter une sec­tion bench­mark^​*​, décou­per la sec­tion des­crip­tion en plu­sieurs sous-par­ties, rajou­ter des sec­tions propres à votre domaine ou au lan­gage de pro­gram­ma­tion, etc.

Pour résu­mer j'ai envie de dire allez à l'essentiel, deman­dez-vous quelle infor­ma­tion vous vou­driez avoir en arri­vant sur le pro­jet, deman­dez des relec­tures par des per­sonnes exté­rieures au pro­jet. Cela prend peu de temps^​†​ et per­met de repé­rer des oublis ou des erreurs bêtes.

Si jamais votre Readme com­mence à être un peu long, pen­sez à rajou­ter une table des matières au début, c'est simple à faire et cela faci­lite la vie de tout le monde. Si il com­mence à être vrai­ment trop grand, il va fal­loir son­ger à créer un manuel uti­li­sa­teur sépa­ré. Cepen­dant, gar­dez quand même les infor­ma­tions de des­crip­tion dans votre Readme pour évi­ter de for­cer l'utilisateur à cli­quer sur un autre lien.

Je tiens à remer­cier les relec­teurs Jona­than Kitt et Gwe­naelle, ain­si que les admi­nis­tra­teurs.

---

1. ^​*​
   qui démon­tre­ra que votre outil est plus rapide et consomme moins de mémoire que la concur­rence
2. ^​†​
   si lire votre Readme prend plus de 5 minutes il va fal­loir éla­guer