L’incroyable pouvoir d’un code bien documenté | de Clive Thompson | décembre 2022

Lorsqu’un projet open source devient un succès, c’est souvent grâce à des documents rédigés avec précision

Ok les nerds, celui-ci est pour vous.

À l’époque où je faisais des recherches mon livre Codeursj’ai parlé à beaucoup de gens qui ont dirigé des projets open source très réussis.

« Qu’est-ce », leur ai-je demandé à tous, « qu’est-ce qui a fait décoller votre projet ? » Pourquoi le vôtre a-t-il pris du galon, alors que tant d’autres — y compris d’assez bons projets — ont langui, et n’ont jamais suscité beaucoup d’intérêt ?

La plupart d’entre eux ont tous dit quelque chose qui a réchauffé mon âme de petit programmeur et d’art libéral :

« Nous avions une très bonne documentation. »

« Documentation » – pour ceux qui ne sont pas déjà branchés dans le marécages de développement de logiciels — signifie ce que cela ressemble. C’est lorsque les codeurs s’assoient pour écrire des instructions précises sur la façon dont, précisément, quelqu’un d’autre peut utiliser leur code open source. Souvent, ils écrivent ces instructions pour d’autres codeurs. Par exemple, il y a quelques mois, j’ai essayé d’utiliser le logiciel javascript Kaboom qui vous aide à écrire des petits jeux vidéoj’ai donc utilisé leur documentation et tutoriels.

La documentation consiste à être un excellent écrivain. Plus précisément, cela nous oblige à faire quelque chose d’assez difficile : nous imaginer à la place de quelqu’un qui n’a jamais utilisé notre code… afin de pouvoir le guider avec soin. Nous devons développer une solide théorie de l’esprit pour le débutant. Nous devons nous passer d’autant de jargon que possible et deviner les éléments de notre code qui pourraient sembler gênants ou déroutants au premier abord.

De nombreux développeurs de logiciels sont terribles à cela. Pour être juste, presque tout le monde est mal à ça; diable, je connais des journalistes à temps plein qui échouent tout le temps à cette tâche.

La rédaction de documentation est, en d’autres termes, un art libéral.

Et si vous y êtes bon ? Putain de merde, cela peut vraiment faire exploser la popularité de votre projet open-source.

J’ai d’abord eu une idée de cela en parlant à Mark Otto, qui en 2011 avec Jacob Thornton a créé « Bootstrap », un petit paquet de code qui vous aide à concevoir et à styliser rapidement un site Web.

Bootstrap a vu le jour lorsque Otto travaillait chez Twitter et voulait aider les développeurs de Twitter à rendre leurs outils plus conviviaux et attrayants. Il a donc assemblé le code Bootstrap ; déposez-le dans votre HTML, et vous pourriez soudainement faire de belles mises en page de grille. Surtout, il a rédigé une documentation claire et attrayante, y compris des exemples d’utilisation.

Ensuite, Otto a décidé de le montrer lors d’un hackathon interne d’une semaine sur Twitter. Au début du hackathon, il a montré le code Bootstrap — et sa documentation — aux 75 équipes de développeurs Twitter, et les a encouragés à l’utiliser. Il leur a également dit de contacter s’ils avaient des questions sur Bootstrap ou sur la façon de l’utiliser : « Mettez-moi au travail si vous avez besoin de moi», comme il se souvenait avoir dit, quand je l’ai interviewé.

Au cours de la semaine, il ne semblait pas que beaucoup de gens aient repris Bootstrap. Sur 75 équipes, seules deux lui ont posé des questions. Pourtant, Otto considérait ces deux questions comme une véritable validation : « J’étais comme, oh génial, un succès incroyable, c’est énorme.”

En réalité, Bootstrap était devenu complètement viral lors du hackathon. Lorsque les 75 équipes ont montré leur code, pleinement demi d’entre eux avaient utilisé Bootstrap.

Mais : Pourquoi ne l’avaient-ils pas contacté ?

Car ils n’en avaient pas besoin. Sa documentation était de premier ordre. Il parlait de lui-même. Il était clair, précis, capturait toutes les choses déroutantes qui pourraient perturber les débutants et incluait de nombreux exemples d’utilisation du code.

Au cours des années suivantes, Bootstrap a explosé en popularité. Lorsque j’écrivais à ce sujet au milieu des années 2010, il s’agissait du référentiel de code le plus populaire de Github depuis quelques années. Aujourd’hui, c’est encore la quatrième bibliothèque la plus étoilée.

Si vous voulez savoir pourquoi Bootstrap a décollé ? Eh bien, c’est évidemment parce que cela a résolu un problème pour des tonnes de codeurs. Il a été fait avec élégance.

Mais cela ne suffisait pas pour réussir. Il y a tonnes de projets logiciels qui cochent ces cases, et ils languissent dans l’anonymat.

Ce qui distingue Bootstrap, c’est sa documentation de premier ordre. Lorsque Thornton et Otto ont publié Bootstrap dans le monde en 2011, ils ont mis en place des documents clairs et étincelants qui ont guidé les gens à travers des tonnes d’exemples en direct du fonctionnement du code. Comme Otto me l’a dit…

Nous vous avons expliqué comment faire ces choses, puis nous vous en avons donné une version rendue en direct – avec le code juste en dessous. Et personne ne faisait vraiment ça, à ce moment-là ! Cela semble un peu trivial maintenant de faire cela aujourd’hui. Mais personne n’avait de documents vraiment simples, avec des exemples en direct que je pouvais simplement copier et coller et exécuter avec.

Je rencontre encore et encore cela. J’ai récemment fait des recherches sur la croissance de Rust, pour un gros morceau sur son histoire pour MIT Tech Review. (Il sortira dans le numéro de printemps, woo !) Maintenant, Rust, comme Bootstrap, a inspiré une énorme quantité de dévotion ; pendant six années consécutives, il s’est classé en tête de la catégorie « les plus aimés » de Stack Overflow dans leur enquête annuelle sur les langues.

Et une chose que j’avais entendue depuis longtemps à propos de Rust ? Il avait une documentation merveilleusement écrite. Rust est un peu complexe à apprendre ; cela oblige les codeurs de langages comme Python ou JavaScript à penser beaucoup plus à la mémoire qu’ils n’en ont l’habitude. Mais les nombreuses personnes qui avaient peaufiné les documents de Rust – y compris les contributions majeures de Steve Klabnik et Carol Nichols – avaient écrit des documents vraiment nets. Une fois, j’ai passé un week-end à bricoler Rust, un débutant totalement trébuchant, mais je ne me suis jamais senti perdu.

L’un des éléments clés d’une documentation étonnante est qu’elle aide le nouveau venu à ne pas être bloqué et à s’éloigner. Si vous avez vraiment précisé ce qu’un débutant doit savoir, il pourra continuer à avancer plus souvent. Ils seront moins souvent coincés à demander des conseils dans un forum qui ne vient jamais. (Surtout, ils n’auront pas besoin de harceler tule développeur open source débordé.) Ils ne rebondiront pas sur votre projet, ne décideront pas, hein, c’est trop difficile à comprendre.

Donc, la leçon est la suivante : si vous avez du code open source que vous souhaitez partager avec le monde ? Si c’est du code utile, tant mieux ! Si c’est élégant, c’est encore mieux !

Mais si vous voulez qu’il décolle, écrivez une documentation fantastique.