Restons courtois ! (Libres conseils 17/42)

Classé dans : Libres Cultures, Open Advice | 9

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.

La plus grande vertu humaine est la politesse. Toutes les autres vertus en découlent. Si vous ne pouvez pas être poli, tout ce que vous accomplirez importera peu.

je lis des livres et mange des nouilles.

9 Réponses

  1. Merci pour ces conseils.
    Vous mettez le doigt sur un point qui fait mal. J’ai souvent tendance à râler après mes utilisateurs, lorsque ceux ci ne comprennent pas des choses « simples ». (Comme utiliser thunderbird plutôt que le webmail orange…).

    Mais ce n’est pas facile, avec personne.
    Les jeunes sont plus « malléables » que leurs ainées, qui souvent se contentent d’utiliser l’ordi, comme un « gadget rigolo ».
    Pas mal d’adultes utilisateurs, n’ont pas grand chose à foutre des principes de base de l’informatique : veulent que ça marche comme la voiture !

    C’est ce à quoi je suis confronté, régulièrement. J’essaie de mettre de l’eau dans mon vin, mais dés fois, j’explose !
    Alors on va essayer une plus grande dilution ! 😉

  2. Anne Onyme

    typo: section « paresse », paragraphe 1:

    « (…) et se tourneront alors vers d’autres choses qu’ils n’auront pas à passer des heures pour comprendre. » –> « (…) et se tourneront alors vers d’autres choses POUR LESQUELLES ils n’auront pas à passer des heures pour comprendre. »

  3. Bonjour, il me semblent qu’il manque un verbe dans la phrase suivante (2° paragraphe de la traduction) :
    « Ceux qui s’impliquent dans les logiciels libres et open source pour tout un tas de raisons différentes. »

    Sans doute vouliez vous écrire :
    « Ceux qui s’impliquent dans les logiciels libres et open source * le font * pour tout un tas de raisons différentes. »

  4. Merci tala, c’est corrigé :).
    @ Anne Onyme : désolé, je ne suis pas d’accord du tout :)

  5. lecteur

    Bonjour, dans la section « L’humilité », il y a une petite faute de frappe au premier paragraphe : « Mais il[s] étaient trop paresseux et trop bêtes pour le faire. » Toutes mes confuses pour la faute que je rajoutais dans un commentaire précédent.

    Ensuite, une remarque. J’ai moi aussi buté sur la phrase que signale Anne Onyme. Mais j’avoue que je bute aussi sur la correction. Peut-être en rajoutant une virule ? « et se tourneront alors vers d’autres choses[,] qu’ils n’auront pas à passer des heures pour comprendre. »
    En relisant, c’est le « pour comprendre » qui me gêne, mais à part dire que ça me gêne (moi et pas forcément d’autres), je ne vois pas de proposition de solution.

  6. Julius22

    Pour faire suite au commentaire d’Anne Onyme, je propose une autre formulation : « (…) se tourneront alors vers d’autres choses SUR LESQUELLES ILS n’auront pas à passer des heures pour comprendre. » ?

  7. merci « lecteur », tala et les autres, tous ces signalements même mineurs sont précieux car ils facilitent le travail ultérieur nécessaire à la version du livre à venir.
    @julius non, toujours pas convaincu :)

    [ « que » qui remplace « les choses » est complément d’objet de « comprendre », pourquoi ajouter un relatif composé ?
    En déroulant la relative, ma phrase donne « ils n’auront pas à passer des heures pour comprendre d’autres choses », la tienne « ils n’auront pas à passer des heures pour comprendre sur d’autres choses »
    Tu préfères quelle version ? ]

  8. Julius22

    😛
    D’accord avec l’explication. Je pensais, en fait, à l’expression « passer des heures sur qqch ». d’où ma proposition. Mais mon dictionnaire me fait défaut sur ce coup-ci.
    (Mais j’ai peut-être aussi du mal avec « avoir à ». Si on utilise « nécessiter » à la place, ça pourrait donner « vers d’autres choses qui ne nécessitent pas des heures pour comprendre ». Et j’ai aussi du mal avec le « pour comprendre ». Si je comprends bien la phrase, le verbe comprendre se rapporte aux autres choses. J’aurais donc tendance à écrire qu’il n’y a pas besoin de « passer des heures pour les comprendre » [les autres choses]. Ce qui donnerait « vers d’autres choses qu’ils n’auront pas à passer des heures pour [ou afin de] les comprendre ». Mais ça commence à faire très lourd, là. :P)
    Sinon, on peut couper la phrase en deux (je n’aime pas les phrases trop longues ; j’ai lu qu’il fallait essayer d’utiliser au maximum douze mots dans les phrases) et changer des termes à la fin : « 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. Ils se tourneront alors vers d’autres choses plus rapides à comprendre. »
    Après, je fais appel à ta sagesse pour trancher (bien que ça n’a pas une importance capitale ; ta proposition m’ira très bien avec tes explications).

  9. La phrase est mal foutue.

    « … et se tourneront vers d’autres choses qu’ils comprendront sans avoir à y passer des heures ».