📃 Comment faire un readme sur GitHub

Le faire, c’est simple. Généralement, vous le générez automatiquement quand vous créez votre repo. MAIS le plus dur, c’est de le rédiger correctement. Et là, on sait tous que c’est une autre paire de manches.

Questions à se poser…

Pour rédiger un readme de qualité, il faut se poser plusieurs questions :

• Qui a fait le projet : si t’es tout seul, c’est toi mais si tu as bossé en groupe sur un projet, la moindre des choses, c’est de mentionner les copains et (parce qu’on est bien élevé) de mettre leur nom/pseudo en lien vers leur github.
• Qu’est-ce que c’est ? Est-ce une recette de choucroute ? Non, c’est une application destiné à l’utilisation mobile pour trouver l’âme sœur pour un public francophone et aimant la rhubarbe. Bah dis-le !
• Quand as-tu bossé dessus ? C’était hier ou y’a trois ans ? Parce que certes, le repo sur GitHub mentionnera les dates mais c’est quand même plus agréable à lire quand un humain t’explique que le website vitrine des amoureux de la crevette grise a été fait durant l’été 2015 à l’occasion d’un hackathon qui s’est déroulé à Miribel.
  Également, la mention des modifications apportées avec le temps peut avoir son importance pour certaines applications. On les notera dans un “changelog” ou encore un “release notes”. Pour l’exemple, on peut aller ici.
• Où t’étais ? Que faisais-tu ? Au cours de ta carrière de développeur, tu seras probablement amené à travailler dans plusieurs boîtes. Ca n’a pas le même sens si tu expliques que tu as travaillé sur un système de facturation quand t’étais Senior Developer chez GrosseBoîtePrestigieuse que si t’étais apprenant chez BeCodeQuiFormeDesNewbies. Explique-nous où tu en étais dans ton parcours professionnel quand t’as pondu ton projet.
• A quoi ça ressemble ? Parce que poster son code, c’est bien mais mettre un petit aperçu sous forme d’une capture d’écran (ou même juste le logo de ton application), c’est mieux. Et un lien vers une démo en ligne c’est encore plus la classe !
• La progression… C’est fini ? C’est en cours ? Tu veux apporter des modifs ? Tu veux qu’on t’aide ?
• Qu’est-ce que ça contient ? Aide-nous à comprendre en une phrase ce qu’on devrait découvrir en plusieurs minutes : est-ce que c’est en MVC, en laravel ? C’est fait de A à Z ? Y’a une base de données ? Si oui, est-ce que le MCD (modèle conceptuel de données) est compliqué ? Tu peux nous le mettre dans le readme ?
• Comment qu’on l’installe ? C’est toujours bien d’expliquer aux copains comment on fait pour installer son travail en local. Soit pour qu’ils puissent l’utiliser, soit pour qu’ils puissent t’aider à l’améliorer !
• D’où ça vient ? D’un client ou d’un exercice à faire en classe… Précise !

Petits exemples pour illustrer

Parce qu’une image vaut mille mots (surtout quand c’est moi qui explique) :

source : https://github.com/GaryLuypaert/php-chat-db-ajax

Voici le readme entier de Gary, apprenant dans la promo 01 de BeCode Anderlecht : https://github.com/GaryLuypaert/php-chat-db-ajax

Petit template pour commencer

Si t’as besoin d’un truc à reprendre et à remplir, fais-toi plaisir avec ceci.