De l’importance de lire la (bonne) documentation

Ma société, accueille en ce moment 2 stagiaires. L’un deux a de grosses lacunes en programmation. C’est un autre aspect de son profil qui m’intéressait quand je l’ai choisi mais l’accomplissement de sa tâche nécessite une bonne dose de programmation. Ce garçon, fort sympathique au demeurant, manque énormément d’autonomie et de méthode de travail. Je passe mon temps à lui dire de lire la documentation.

Il n’est malheureusement pas le premier que je vois préférer des tutoriaux plus ou moins mal ficelés mais rédigés dans la langue de Molière Lorie à la documentation officielle pourtant forcément plus complète et plus à jour mais en anglais. L’un de mes professeurs disait qu’un informaticien ne parlant pas anglais est handicapé. Je partage totalement ce point de vue. Quand on voit la différence tant en quantité qu’en qualité des informations disponibles en français et en anglais, cela est une évidence.

À force, mon stagiaire a tout de même fini par prendre l’habitude de regarder la documentation pour éviter de se prendre un RTFM bien senti suite à une question saugrenue. Cette après-midi, il devait réaliser une requête SQL un peu tordue. Je précise que nous utilisons exclusivement MySQL comme SGBD. Ne réussissant pas trouver de réponse à son problème dans la documentation, il sollicite mon aide. Surpris par ce qu’il me dit y avoir lu, je vérifie la page qu’il consulte. Il regardait la documentation de PostgreSQL ! Voyant ma surprise, il me balbutie que ce n’est pas exactement la bonne documentation mais que ça doit fonctionner pareil … en gros.

Ce contenu a été publié dans Développement Web. Vous pouvez le mettre en favoris avec ce permalien.

16 réponses à De l’importance de lire la (bonne) documentation

  1. Seza dit :

    Quel age a-t-il ? Je repense à moi tout naïf quand je découvrait que chaque touche du clavier pouvais servir.

    J’avoue que je ne suis pas un spécialiste en anglais, et les docs shakespearienne je m’y mélange très souvent les pinceaux par manque de vocabulaire et ça me freine terriblement dans mes recherches. Alors je regrette mon lycée et les cours d’anglais. 100% d’accord avec toi.

    Afin de complété mon vocabulaire français ce coup çi ? RTFM, kézako (même si j’en devine le sens) ?

  2. Super Chinois dit :

    Tout le monde a au moins pris un RTFM dans la tronche une fois dans sa vie. C’est comme une bonne cuite, je dirais que ça peut arriver sans faire exprès 😉

  3. Greg dit :

    L’autonomie dans le boulot et la lecture de doc, j’y ai été confronté dans mon premier boulot car j’avais en charge de développer un intranet d’entreprise interfacé avec l’ERP en fonction. Autant dire que ça a été formateur, mais je me rappelle m’être vraiment cassé les dents sur certains problèmes … qui me font doucement rire maintenant.

    Avec le recul, je constate que la doc PHP est vraiment bien foutue comparée à certaines autres (MSDN notament).

    Pour info, RTFM signifie "Read the f*cking manual !", ce qui pourrait se traduire par "Va lire cette p*tain de doc !" 😉

  4. Nath dit :

    Mon avis dans ce domaine est plus mitigé.
    Je pense qu’un bon tuto (au besoin en français), permet de prendre en main et de comprendre plus facilement la philosophie d’un outil.

    Après, la doc permet d’aller plus loin et de répondre à des problèmes précis. Mais c’est vrai que, même si je me débrouille en anglais, je préfère toujours la version française quand elle existe. Ca me permet de mettre toute ma concentration sur la technique, plutôt que de réserver une partie de mes efforts à la compréhension.

  5. yannux dit :

    "RTFM" devrait être graver dans notre mémoire dès la naissance :).
    J’aime beaucoup allier documentation et tutoriaux.
    Pour PHP la doc est largement suffisante en général, vraiment excellente.
    La doc Mysql ça va quand je sait où chercher, mais avec une recherche sur quelques mot clés…. finalement merci google aussi !

  6. fredmac dit :

    Demander systematiquement à son stagiare de lire la documentation c’est un peu facile ; cela nous décharge de notre tâche de transmission du savoir. S’il suffisait de prendre une doc pour devenir un ponte en prog cela se saurait. Prendre un stagiaire n’est pas un caprice…
    Par contre, nous avons probablement en mémoire, un prof, un tuteur de stage qui à pris le temps de nous expliquer les choses… expliquer et plus long, et plus "dur comme faire" que de renvoyer ce chère stagiaire à sa doc… ne pas oublier d’où nous venons.

  7. JMF dit :

    fredmac> Demander à un stagiaire de systématiquement regarder la doc avant de poser une question me semble parfaitement normal puisque c’est ce que je fais moi-même. Le problème n’est pas d’être stagiaire ou non mais de ne pas poser de question idiote.

    Ceci étant dit, RTFM n’est pas la seule réponse que j’ai à offrir bien entendu. Personne ne peux tout savoir, moi le premier. J’aide de mon mieux mes stagiaires mais je cherche également à les rendre autonomes.

    Tu sais aussi bien que moi qu’il est beaucoup plus simple de poser la question qui vient de te traverser l’esprit à la personne assise en face de toi que de chercher dans la documentation. Seulement ça pose deux problèmes : on n’apprend pas à chercher, on distrait l’autre et lui fait donc perdre sa concentration. Si la question est légitime, cela se justifie mais si c’est pour demander une évidence, cela me dérange plus.

    Sans vantardise déplacée, je trouve généralement la réponse à ses questions en moins d’une minute en consultant la documentation. Mon intervention n’est donc pas indispensable. Je vois trop de gens incapables d’exploiter une documentation. J’estime que c’est également (donc pas seulement) mon rôle de tuteur.

    Ceci étant dit, le rôle du tuteur va bien au-delà et je prends le temps de lui expliquer certains aspects plus complexes à assimiler.

  8. Perrich dit :

    Ce n’est malheureusement pas nouveau ce problème d’autonomie… Je pense que le problème principal est lié à la motivation. Si on est motivé, peu importe le métier et/ou ce que l’on doit faire, on le réalise.
    Quelqu’un de motivé et ayant envie de reussir va essayer de trouver une solution et dans le pire des cas demander (le problème c’est aussi de demander et de ne pas attendre vraiment le pire des cas !). Alors que d’autres feront soit un effort mais sans aboutir et/ou choisiront la solution de facilité à savoir la mailing-list, le forum ou la question aux collegues.

    Il n’y a qu’a voir sur les forums le nombre de question récurrente pour ne plus douter de la faignantise des gens. Il n’y a qu’a regarder les questions souvents HS posées sur les mailing-list. Après si l’on dit quelque chose, on va nous expliquer que tout est lié et que l’on a pas trouvé son besoin avant de poser la question…

    Il est vrai que choisir un stagaire (mais aussi un employé) n’est pas aisée, de même que de "travailler ensemble". Cependant, si on ne dit jamais a quelqu’un les bonnes pratiques, il ne les appliquera pas ! Et la première des bonnes pratiques c’est de lire la doc, de chercher dedans etc. C’est pas en l’évitant que l’on apprendra véritablement les choses. Ce n’est pas non plus en lisant des tutoriaux. Un tutorial, c’est bien pour démarrer, pour faire quelque chose pas à pas mais ensuite il est interressant de savoir si il décrit quelque chose à réelement suivre. Il ne faut pas rester stupide et prendre un tutorial ecrit en 2001 sur la gestion des sessions PHP ou sur la lecture de XML en PHP en croyant que c’est la solution miracle.

    Je suis entièrement de ton avis jean-marc, il est clair qu’il est plus utile pour ton stagiaire :
    1. d’acquerir les méthodes pour savoir se débrouiller
    2. d’avoir des astuces ou des aides sur les choses réelement apporteuses et importantes (et non sur comment decouper une chaine et la mettre dans un tableau en PHP)

    Maintenant, je pense que l’on est un peu tous pareil et on se fait toujours avoir sur certaines choses. Dernièrement j’ai vu quelqu’un disant connaitre le SQL indiquer LIMIT 1 dans une requete alors que LIMIT est spécifique à certains SGBD ou encore utiliser un COUNT() pour faire une somme. Hou, c’est nul… Oui sauf qu’il m’est arrivé dernièrement d’implémenter un upload de fichier en Java (l’horreur comparé à PHP !), j’ai utilisé une librairie de jakarta.commons pour faire cela. J’ai lu les exemples de la doc et j’ai mis en prod après quelques tests. Résultat, avec un gros fichier, par défaut, le comportement change et résultat ce que j’avais fait plantait. Comme quoi, il faut lire la doc jusqu’au bout !

  9. Seza dit :

    Merci pour le sens de RTFM, je ne connaissais pas peut être parce que je n’ai pas fait d’école.

    Personnellement je trouve qu’être autodidacte est une bonne formation. Ça apprend forcément la débrouillardise. Par contre j’aurais souvent apprécier le conseil d’un initié pour faire les bons choiox et prendre les bonne route.

    Ceci dis je suis d’accord avec la démarche, il doit apprendre à se débrouiller. Avec mes collègues non informaticiens/programmeurs qui viennent souvent me dérnager avec des questions que je qualifie d’inutile, ma démarche est de les orianté vers la réponse sans leur répondre. Afin qu’il cherche sans tropo se perdre. Genre "J’ai plus internet" -> "AS tu regardé ton cable ?". Si il reviens alors je me déplace sur son poste.

  10. fredmac dit :

    Jean-Marc -> il existe une amplitude profonde sur la perception d’un savoir, selon que l’on maîtrise ou non, le dit savoir.

    Dis autrement, ce qui nous semble simple ["à nous qui savons"], ne l’est pas nécessairement pour les autres…

    Concernant cette problématique d’autonomie que vous appellez tous de vos vœux, j’aimerais vous dire que l’autonomie s’acquière ; on ne nait pas autonome, on le devient.
    Vous souhaitez que vos stagiaire deviennent autonomes, soit : que faites vous en ce sens ? Va lire la doc est un peu court, non ?

    Cela dit, la pédagogie trouve un <em>"cas d’école"</em> si j’ose dire avec le stage en entreprise (méthodologie, porté, temps…).

  11. JMF dit :

    fredmac> Je trouve assez injuste le procès d’intention que tu me fais malgré mes explications…

  12. pascal dit :

    j’aide le stagiaire d’un collègue régulièrement.

    je pratique le RTFM, mais pas de façon abrupte :
    _ ce que tu cherches, c’est sur une chaine. donc regardes du coté de str* dans le manuel
    _ là tu abuses, tu as oublié tel truc

    le truc c’est aussi de dire COMMENT trouver l’info, comme je lui montre comment trouver ses bugs. l’autonomie, ça passe par la capacité à apprendre et se démerder.

  13. fredmac dit :

    Ces explications me semblent courtes. Néanmoins, si mes propos te semblent déplacés… retire les… je ne m’en offusquerais pas.

    En tous cas je tient à te remercier d’avoir laissé les commentaires ouverts sur ton blog.

  14. JMF dit :

    fredmac> J’essaie de ne modérer les commentaires de ce blog qu’en cas de dérapage grave. Ne pas être d’accord avec moi, du moment qu’on s’exprime avec respect, n’entre pas dans cette catégorie. 😉

    En tout cas, j’essaie toujours d’écouter les remarques et même si cela ne change que rarement ma position sur le moment, j’y réfléchi longtemps après et parfois cela fait son chemin dans ma petite tête.

  15. Greg dit :

    Pour ma part, je pense qu’un minimum d’autoformation est indispensable quelque soit le cursus professionnel. Lorsque j’ai commencé à bosser, je me suis retrouvé en contrat de qualif’ dans une boite où il n’y avait aucun développeur PHP pour m’aider et mon chef n’était pas développeur lui-même.

    Dans un premier temps, j’ai utilisé la solution de facilité : les forums …
    C’était tellement une solution de facilité que je suis même devenu plus actif sur les forums que je fréquentais, au point même de devenir modérateur sur l’un d’eux. Bref, je suis moyennement d’accord pour le terme de "solution de facilité" pour parler de ce medium. L’avantage d’un forum (ou d’une mailing list) permet de confronter sa solution ou son problème à un panel de personnes qui pourront réorienter le problème et éventuellement proposer autre chose. Pour moi, c’est le parfait complément d’une bonne doc.

    Pour revenir à ma petite histoire, j’ai ensuite du apprendre l’autonomie rapidement et sur divers aspects : codage, montage de serveur web, interfaçage avec les outils existants. Au final, j’estime que c’est une des meilleurs expériences que j’ai pu avoir au cours de ma formation. Je sais maintenant me débrouiller et où chercher pour trouver des réponses à mes questions … si jamais ça devient vraiment hardu, il me restera toujours les forums et quelques potes qui s’y connaissent ! 😉

  16. br1o dit :

    Je ne suis pas sûr que seule la méconnaissance de l’anglais soit un obstacle pour lire une documentation. J’ai remarqué, comme toi, que les termes "documentation" et "officielle" avaient tendance à faire fuir.

    Au-delà des explications liées à la motivation (qui restent dépendantes de l’individu), je me demande quelle est la part des méthodes scolaires dites "globales" d’apprentissage de la lecture, par exemple.

    Je ne pourrais pas développer ce sujet par manque de connaissances précises, mais mon intuition me souffle que les méthodes basées sur la reconnaissance globale des formes des lettres pour repérer le sens des mots doivent avoir une influence sur la capacité des apprenants à faire les efforts nécessaires pour suivre le plan structuré (forcément un peu laborieux) d’une doc officielle bien pensée.

Les commentaires sont fermés.