Chaque jeudi à 21h, rendez-vous sur le framapad de traduction, le travail collaboratif sera ensuite publié ici même.

Traduction Framalang : peupleLa, goofy, lamessen, SaSha_01, lerouge, Kalupa, RavageJo, lenod, Sky, Astalaseven, Alpha, KoS, purplepsycho +tala

De L’importance des bonnes manières

Rich Bowen

Rich Bowen a travaillé dans le domaine du logiciel libre et open source pendant près de quinze ans. La majeure partie de son travail a porté sur le serveur HTTP Apache ; il a également travaillé sur Perl, PHP et diverses applications web. Il est l’auteur de Apache Cookbook, The Definitive Guide to Apache et divers autres livres. Il fait également de fréquentes apparitions dans diverses conférences sur les technologies.

J’ai commencé à travailler sur le projet de documentation du serveur HTTP Apache en septembre 2000. Du moins, c’est à ce moment-là que j’ai réalisé mon premier commit dans les docs. Auparavant, j’avais présenté quelques corrections par courriel, et quelqu’un d’autre les avait appliquées.

Depuis cette période, j’ai réalisé un peu plus d’un millier de modifications de la documentation du serveur HTTP Apache, ainsi qu’une poignée de modifications du code lui-même. Ceux qui s’impliquent dans les logiciels libres et open source le font pour tout un tas de raisons différentes. Certains tentent de se faire un nom. La plupart essaient de « gratter là où ça les démange » comme ils disent, s’efforçant d’ajouter une fonctionnalité, ou de créer une nouvelle brique logicielle pour satisfaire un de leurs besoins.

Je me suis impliqué dans l’écriture de la documentation sur des logiciels parce que j’avais été enrôlé pour aider à l’écriture d’un livre et que la documentation existante était vraiment horrible. Donc, pour rendre le livre cohérent, j’ai dû discuter avec différentes personnes du projet afin qu’elles contribuent à donner du sens à la documentation. Lors de la rédaction de l’ouvrage, j’ai amélioré la documentation, avant tout pour me faciliter la tâche. À peu près à la même époque, Larry Wall, le créateur du langage de programmation Perl, promouvait l’idée selon laquelle les trois principales qualités d’un programmeur étaient la paresse, l’impatience et l’arrogance. Selon moi, Larry avançait des arguments fondés et avec un sens de l’humour certain. Néanmoins, une partie non négligeable de la communauté des programmeurs a pris ses paroles comme un permis de connerie.

La paresse

Nous écrivons de la documentation pour ne pas avoir à répondre aux mêmes questions tous les jours pour le restant de notre vie. Si la documentation est insuffisante, les gens auront des difficultés à utiliser le logiciel. Bien que cela puisse être la source d’une activité lucrative de consultant, il s’agit aussi du meilleur moyen de faire avorter un projet, car les gens abandonneront, frustrés, et se tourneront alors vers d’autres choses qu’ils n’auront pas à passer des heures pour comprendre.

Ainsi, la paresse est la première vertu d’un rédacteur de documentation. Quand un client pose une question, nous devrions répondre à cette question en profondeur. Et même, de la façon la plus complète possible. Nous devrions alors enregistrer cette réponse pour la postérité. Nous devrions l’enrichir avec des exemples et si possible des diagrammes et des illustrations. Nous devrions nous assurer que le texte est clair, grammaticalement correct et éloquent. Nous devrions alors l’ajouter à la documentation existante dans un endroit facile à trouver et largement référencé partout où quelqu’un pourrait le chercher.

La prochaine fois que quelqu’un posera la même question, nous pourrons lui répondre avec un lien vers la réponse. Et les questions que l’on pourrait poser après l’avoir lue devraient être la source d’améliorations et d’annotations à ce qui a déjà été écrit. C’est la vraie paresse. La paresse ne signifie pas simplement se dérober au travail. Cela veut aussi dire faire le travail si bien qu’il n’aura pas à être refait.

La patience

ll existe une tendance dans le monde de la documentation technique à être impatient et querelleur. Les sources de cette impatience sont nombreuses. Certaines personnes pensent que, comme elles ont dû travailler dur pour comprendre ces choses, vous le devez aussi. Beaucoup d’entre nous dans le monde du technique sommes des autodidactes et nous avons peu de patience pour ceux qui viennent après nous et veulent accéder rapidement au succès. J’aime appeler ça le comportement du « tire-toi de mon chemin ». Ce n’est pas vraiment constructif.

Si vous ne parvenez pas à être patient avec le client, alors vous ne devriez pas être impliqué dans le service clientèle. Si vous vous mettez en colère quand quelqu’un ne comprend pas, vous devriez peut-être laisser quelqu’un d’autre gérer la question.

Bien sûr, c’est très facile à dire, mais beaucoup plus difficile à faire. Si vous êtes un expert sur un sujet particulier, les gens vont inévitablement venir à vous avec leurs questions. Vous êtes obligé d’être patient, mais comment allez-vous y parvenir ? Cela vient avec l’humilité.

L’humilité

J’ai fait de l’assistance technique, en particulier par liste de diffusion, pendant à peu près deux ans, quand j’ai commencé à suivre des conférences techniques. Ces premières années ont été très amusantes. Des idiots venaient sur une liste de diffusion et posaient des questions stupides que des milliers d’autres perdants avaient posées avant eux. Et si seulement ils avaient regardé, ils auraient trouvé toutes les réponses déjà données auparavant. Mais ils étaient trop paresseux et trop bêtes pour le faire.

Ensuite, j’ai assisté à une conférence, et j’ai constaté plusieurs choses. Tout d’abord, j’ai découvert que les personnes qui posaient ces questions étaient des êtres humains. Ils n’étaient pas simplement un bloc de texte écrit noir sur blanc, à espacement fixe. Il s’agissait d’individus. Ils avaient des enfants. Ils avaient des loisirs. Ils connaissaient beaucoup plus de choses que moi sur une grande variété de sujets. J’ai rencontré des gens brillants pour qui la technologie était un outil qui servait à accomplir des choses non techniques. Ils souhaitaient partager leurs recettes avec d’autres cuisiniers. Ils souhaitaient aider les enfants d’Afrique de l’Ouest à apprendre à lire. Ils étaient passionnés de vin et voulaient en apprendre davantage. Ils étaient, en bref, plus intelligents que moi, et mon orgueil était le seul obstacle sur la route de leur succès.

Quand je suis revenu de cette première conférence, j’ai regardé les utilisateurs de listes de diffusion sous un tout autre jour. Ce n’étaient plus des idiots posant des questions stupides, simplement des gens qui avaient besoin d’un peu de mon aide pour pouvoir accomplir une tâche. Pour la plupart, la technologie n’était pas une passion. La technologie était seulement un outil. Il était donc compréhensible qu’ils n’aient pas passé des heures à lire les archives de la liste de diffusion de l’année passée et choisissent plutôt de reposer des questions.

Bien entendu, si un jour les aider devient pénible, la chose la plus polie à faire est de prendre du recul et de laisser quelqu’un d’autre répondre à la question plutôt que de leur dire que ce sont des imbéciles. Mais il faut aussi se rappeler toutes les fois où j’ai eu à poser des questions stupides.

La Politesse et le Respect

En fin de compte, tout cela se résume à la politesse et au respect. J’ai principalement abordé la question de l’assistance technique, mais la documentation n’est rien d’autre qu’une forme statique d’assistance technique. Elle répond aux questions que vous attendez des gens et elle offre des réponses dans une forme semi-permanente à titre de référence.

Lorsque vous écrivez cette documentation, vous devriez essayer de trouver le juste équilibre entre penser que votre lecteur est un idiot et penser qu’il devrait déjà tout savoir. D’un côté, vous lui demandez de s’assurer que l’ordinateur est branché, de l’autre, vous utilisez des mots comme « simplement » et « juste » pour faire comme si chaque tâche était triviale, laissant au lecteur l’impression qu’il n’est pas tout à fait à la hauteur.

Cela implique d’avoir beaucoup de respect et d’empathie pour votre lecteur, en essayant de vous rappeler ce que c’est que de débuter ou d’avoir un niveau intermédiaire dans l’apprentissage d’un nouveau logiciel. Cependant, les exemples de mauvaise documentation sont si répandus qu’il ne doit pas être difficile de s’en souvenir. Il y a des chances que vous en ayez fait l’expérience au cours de la dernière semaine.

J’aurais aimé…

J’aurais aimé être moins arrogant quand j’ai commencé à travailler sur la documentation open source. Quand je relis ce que j’ai pu écrire sur des listes de diffusion archivées publiquement, gravées à jamais dans le marbre d’Internet, j’ai honte d’avoir été aussi grossier.