Lorsque j’étais un utilisateur et un programmeur débutant de Unix, la réponse que l’on me faisait à toute question technique était RTFM, ce qui signifie « Read the F… Manual » (Lisez le manuel d’utilisation).
Malheureusement, cela n’a pas changé pour les nouvelles générations d’utilisateurs et de développeurs de Linux et des logiciels libres.
Il est grand temps de s’attaquer à ce problème et d’apporter des changements positifs. Les manuels et la quasi-totalité de la documentation sont souvent obsolètes, parfois impossibles à lire, voire inexistants.
Tout le monde se plaint, se lamente
Ce n’est pas comme si nous n’étions pas au courant de ce problème. Jon Corbet, rédacteur en chef de LWN, la meilleure publication sur Linux et superviseur de la documentation du noyau Linux, en parle depuis qu’il travaille sur Linux. Mais personne ne fait jamais rien à ce sujet.
Tout le monde se plaint, se lamente. Mais personne ne travaille sur la question. En fait ce n’est pas tout à fait juste. Certaines personnes ont travaillé dur sur la documentation.
En effet, Alejandro Colomar, qui a maintenu le projet Linux man-pages pendant les quatre dernières années, vient de démissionner. Pourquoi ? C’est simple. « Je l’ai fait pendant mon temps libre, et aucune entreprise n’a sponsorisé ce travail… Je ne peux plus soutenir ce travail économiquement » dit-il.
Une documentation de mauvaise qualité
Qui peut le lui reprocher ?
« Je me suis souvent plaint que même si des milliers de développeurs sont payés pour travailler sur le noyau Linux, il n’y a pas une seule personne dont le travail consiste à écrire de la documentation pour le noyau » souligne Jon Corbet,
De fait des gens écrivent de la documentation. « Il y a beaucoup de développeurs qui écrivent de la documentation. Ne vous méprenez pas. Certains y travaillent très dur. Mais ce n’est généralement pas pour cela que leurs employeurs les paient » poursuit-il.
Quelques années plus tôt, Corbet avait souligné que « personne ne veut payer pour la documentation » et qu' »il n’y a personne dont le travail consiste à écrire de la documentation pour le noyau (Linux) ».
Ce manque de ressources dédiées se traduit donc par une documentation de mauvaise qualité.
C’est un problème. C’est un vrai problème.
La documentation du noyau Linux est… laide
Conséquence, la documentation du noyau Linux est… laide. Lors de la réunion 2022 des Linux Plumbers, Corbett a fait la remarque suivante :
« Quand je suis arrivé pour maintenir la documentation du noyau, tout était jeté dans le répertoire principal de premier niveau. Nous l’avons donc amélioré, mais nous sommes toujours dans une situation qui me rappelle beaucoup la chambre de ma fille, où les objets sont jetés n’importe où ».
La situation s’est améliorée depuis. Mais elle n’est toujours pas, disons, adaptée aux débutants.
Le fait que la documentation du noyau consiste en « des milliers de documents individuels » écrits de manière isolée plutôt qu’en un ensemble cohérent de documentation n’aide en rien. Bien que des efforts aient été faits pour organiser les documents, la documentation globale manque toujours d’une structure unifiée.
La situation n’est pas meilleure dans d’autres projets open source
Steve Rostedt, ingénieur logiciel chez Google et développeur du noyau Linux, est d’accord. Lors de la conférence Linux Plumbers de l’année dernière, a déclaré que : « lorsqu’il rencontre des bugs, il ne peut pas trouver de documents décrivant le fonctionnement des choses« . Si quelqu’un d’aussi expérimenté que Rostedt a des difficultés, imaginez la migraine des programmeurs novices !
Oui, j’ai parlé de Linux. Mais la situation n’est pas meilleure dans d’autres projets open source. Beaucoup d’entre eux, même les plus populaires, ont du mal à maintenir une documentation complète et à jour. Pourquoi ? En raison de fonds insuffisants et d’un développement trop rapide. Je veux dire par là que lorsque votre code est publié dans un pipeline Continuous Integration/Continuous Delivery (CI/CD) qui met les programmes en production tous les jours ou tous les deux jours, la documentation ne sera jamais complètement à jour.
Mais ici, nous ne parlons pas de ma mise à jour de la documentation. La question se pose même sur les documents et manuels de base utiles pour les développeurs, les administrateurs système et les utilisateurs.
Un fichier README comme simple documentation
Beaucoup trop de projets GitHub, par exemple, n’ont qu’un fichier README comme documentation. Ce n’est pas utile.
D’autres projets ne semblent tout simplement ne pas se soucier de la documentation. Prenons, par exemple, mon interface de bureau Linux préférée, Cinnamon. Beaucoup de gens l’utilisent et l’adorent. Mais il n’y a pas de site web pour les utilisateurs. Tout ce qu’il y a, c’est une page GitHub. Les Linux Mint Forums et la communauté sont formidables. Mais vous devez faire de sérieuses recherches pour trouver la réponse à votre problème du jour.
Alors, que pouvons-nous faire ? OpenSource.com propose une bonne liste des meilleures pratiques en matière de documentation.
- Valoriser les contributions à la documentation au même titre que les contributions au code.
- Placer la documentation et le code dans le même repo du projet.
- Faire de la documentation une exigence pour une étape de fusion ou de publication.
- Avoir un processus de contribution cohérent pour le code et la documentation.
- Disposer de processus bien documentés pour contribuer à la documentation.
C’est très bien. Mais bonne chance pour amener les gens à valoriser les contributions à la documentation autant que le code. La documentation a toujours été l’enfant négligé de la programmation.
Voici la solution
Voulez-vous connaître le vrai secret pour améliorer la documentation des projets open-source ?
Vous êtes prêt ?
Payez les rédacteurs. Voilà.
La rédaction d’une documentation – qu’il s’agisse d’un manuel de 500 pages, d’un mode d’emploi rapide et pratique ou d’une FAQ – est un travail difficile. Croyez-moi. J’ai fait tout cela, et franchement, même si je continue à écrire des articles pratiques pour ZDNET de temps en temps, personne ne peut me payer suffisamment pour écrire de la documentation sérieuse. Et encore moins des manuels techniques. C’est tout simplement trop de travail pour pas assez d’argent.
Donc, si vous voulez vraiment aider Linux ou votre projet open-source préféré, faites en sorte de payer de l’argent à des programmeurs ou à des rédacteurs compétents pour écrire de la documentation. Le monde de la technologie n’en sera que meilleur.