- esbuild et Redis sont deux exemples de codebases dotées d’une documentation remarquable.
- Grâce au README, au journal des modifications, aux documents d’architecture et aux commentaires dans le code, même les nouveaux venus peuvent comprendre la structure du codebase, son fonctionnement et les raisons derrière les choix effectués.
- Il s’agit d’excellentes études de cas pour les développeurs qui souhaitent améliorer la documentation du code et de l’architecture logicielle.
Pourquoi une bonne documentation est importante
- Lorsqu’on développe un logiciel, une bonne documentation est essentielle, en particulier lorsque d’autres personnes consultent le codebase ou y contribuent, ou lorsque l’on doit soi-même s’y référer plus tard.
- Les utilisateurs de logiciels rencontrent souvent des difficultés à cause d’une documentation manquante.
- Si vous contribuez à un codebase, plus la qualité de la documentation est élevée, plus vous pouvez contribuer rapidement.
- La qualité de la documentation influence directement ou indirectement l’expérience de l’auteur, des contributeurs et des utilisateurs.
- Les bénéfices d’une bonne documentation sont nombreux : gain de temps, augmentation des contributions externes aux projets open source, conservation de l’historique des décisions passées, meilleure accessibilité pour davantage d’utilisateurs, structuration de la réflexion et mise en évidence des problèmes.
La documentation d’esbuild
- esbuild est un bundler JavaScript créé par Evan Wallace.
- Le README d’esbuild est centré sur les utilisateurs finaux de l’outil.
- Avec des liens vers les sections principales de la documentation et une section « Pourquoi ? », il explique brièvement pourquoi choisir esbuild plutôt qu’un autre bundler.
- Les documents d’architecture d’esbuild se trouvent dans le répertoire
docs, sous la forme des fichiers architecture.md et development.md.
- La documentation d’architecture explique les principes de conception et inclut non seulement du texte, mais aussi des illustrations pour présenter les concepts.
- Le journal des modifications d’esbuild est détaillé, avec des résumés, des explications approfondies et des exemples de code avant/après les changements.
La documentation de Redis
- Redis est une base de données en mémoire.
- Le README de Redis partage les mêmes qualités que celui d’esbuild, tout en s’adressant à la fois aux contributeurs et aux utilisateurs finaux.
- La section consacrée aux internals de Redis comprend la structure du code source et des explications sur les fichiers principaux.
- Les commentaires dans le code source de Redis fournissent plusieurs paragraphes d’explication pour une seule ligne de code.
Conclusion
- De nombreux projets open source disposent d’une excellente documentation.
- esbuild et Redis sont particulièrement impressionnants à cet égard.
- La documentation peut représenter une contrainte de temps à court terme, mais elle permet d’en gagner sur le long terme.
- Pour les projets utilisés ou enrichis par de nombreuses personnes, l’absence de documentation mérite d’être sérieusement reconsidérée.
L’avis de GN⁺
- Les exemples de documentation d’esbuild et de Redis soulignent auprès des développeurs l’importance d’une documentation qui facilite la compréhension et la maintenance d’un codebase.
- La documentation est un élément clé pour renforcer la pérennité d’un projet et encourager la participation de la communauté.
- Dans le cas d’esbuild, au-delà de son rôle de bundler JavaScript rapide, son excellente documentation semble avoir contribué à la croissance du projet.
- Redis a eu un impact positif sur la communauté des développeurs grâce à une documentation qui aide à comprendre facilement un système complexe de base de données en mémoire.
- Ces exemples peuvent aussi aider à diffuser l’importance de la documentation auprès d’autres projets open source, et sont particulièrement utiles pour aider les ingénieurs logiciels débutants à mieux comprendre comment documenter leurs propres projets.
2 commentaires
esbuild, et pas seulement son fichier README.md, a un fichier architecture.md présenté dans l’article qui est vraiment magnifique !
Commentaire Hacker News
Antirez, le créateur de Redis, a rédigé sur son blog un billet détaillant sa réflexion sur les commentaires dans le code. Il y identifie 9 types de commentaires utilisés dans Redis.
Un article bien écrit, avec des exemples concrets et des captures d’écran, sur ce qui peut faire l’excellence de la documentation d’un projet pour les utilisateurs, les développeurs et les contributeurs.
Cela montre l’attention portée par les mainteneurs à la qualité du dépôt.
Cela rappelle la série « The Architecture of Open Source Applications », qui contient des éclairages intéressants.
La documentation de GitLab a la réputation d’être très bonne, mais il n’a pas souvent été nécessaire de l’utiliser directement. D’où la question de savoir si leur documentation d’architecture est du même niveau.
Le projet Postgres accorde lui aussi une attention très détaillée à la documentation, aux fichiers readme et aux commentaires dans le code.
La documentation d’architecture du projet esbuild a fortement impressionné. On aurait aimé disposer d’une telle documentation dans certaines bases de code sur lesquelles on a travaillé par le passé.
Les changelogs des projets open source sont particulièrement appréciés. Ils sont bien plus professionnels et instructifs que ceux d’autres entités à but lucratif. Critique notamment du changelog de l’application de la banque ING, qui devrait davantage informer que chercher à être drôle.
« Le plus grand manque aujourd’hui dans la communauté du logiciel libre n’est pas le logiciel, mais l’absence de bonne documentation libre pouvant accompagner le logiciel libre. »
Il est rappelé que Redis n’est plus open source. Redis est désormais un logiciel « source-available » sous Redis Source Available License v2 (RSALv2) et Server Side Public License v1 (SSPLv1).