Le site de Xavier
De la documentation.
Il en va des documentations comme des champignons. Les endroits où l'on en trouve à foison, avec une qualité n'ayant d'égal que la quantité, sont rares et peuvent valoir cher.
Parfois, ceux qui écrivent des documentations, fussent-elles laconiques, se moquent de nous. Ils se sentent obligés de tenter de nous expliquer la procédure ; procédure dont tout le monde sait qu'elle va rater lamentablement. Les types qui écrivent "Ouverture facile" sur les plats cuisinés doivent avoir un petit coté pervers. Le vice qui les habite est tel qu'ils les poussent souvent jusqu'à détailler à outrance cette procédure vouée à l'échec : "Ouverture facile, tirer ici".
On admirera aussi l'exploit de développeurs d'une certaine bibliothèque dont on taira le nom par charité. Écrire 500 pages bien tassées sans un seul exemple mérite au moins une médaille olympique dans la catégorie "fous furieux". L'exemple se fait rare. L'exemple se fait désirer. L'exemple se terre à la page 4242. Rarement avant. Certains geeks, éreintés par l'effort colossal de rendre un tant soit peu utile cette bibliothèque (qui leur a coûté N nuits de sommeil) en rédigeant une documentation, s'amusent à donner de faux exemples. Qui n'a jamais trouvé, page N<10, un morceau de code ressemblant à un beau et bon bolet, près à être dégusté/compilé pour amener notre cerveau (ou notre estomac --c'est très lié--) sur les chemins escarpés de la compréhension du mode de fonctionnement de la susdite bibliothèque qui occupe nos soirées depuis trop longtemps ? Malheureux ! Bienheureux celui qui croit que ça va se passer de la sorte. Les soucis lui sont inconnus. Ce bolet aura été mangé de l'intérieur par les vers. Jamais il ne compilera. Pire, si, un miracle mettant à contribution tout le panthéon grec, il compile, il ne fera jamais ce que la documentation en dit en des termes si ténébreux qu'un bouillard anglo-normand en devient limpide par comparaison.
Peut-on imaginer un chirurgien posant une plaque sur un os, seul et pour la première fois, ayant seulement connaissance des petits détails de l'intervention ? Peut-on imaginer qu'il n'ait jamais eu ni vision globale de ce geste opératoire, ni vu la moindre demonstration ? Ho bien sûr, la sacro-sainte documentation s'entend sur des pages pour lui expliquer comment l'effort de vissage dépend du pas de vis. Mais de là à savoir s'il va lui falloir trouver un Hercule pour visser sa plaque ou pas, l'histoire est toute autre. (Ceux qui suivent auront remarqué qu'Hercule est occupé à faire compiler le bolet. Ne pouvant pas tout faire non plus ce sera donc compliqué si le chirurgien théoricien a besoin de lui).
Il en va de la doc sans exemples comme de la doc ultra-verbeuse : Au panier! La page A0 pour (tenter d')expliquer comment fonctionne un radio-réveil. Le roman pour dire que oui oui oui, il faut appuyer sur le déclencheur pour que la photo soit prise. Les 25 pages décrivant toutes les fonctionnalités de mon téléphone sauf celle qui permet de l'empêcher de prendre l'initiative de faire de l'art en prenant des photos dont les titres pourraient être "Intérieur de poche 1", "Intérieur de poche 2", "Intérieur de poche 3"... et pour cause puisqu'elle n'existe pas. Voilà quelques dignes représentants de la surverbosité.
Les long fleuves documentaires sans exemples ne sont alimentés que par l'eau des glaciers fondus par le réchauffement provoqué par la combustion du papier qui les porte, papier qui, une fois entaché de la sorte, ne mérite pas d'autre crépuscule que la purification par le feu afin d'avoir une fin digne.
Keep It Simple and Stupid. Keep It Sweet and Simple. Keep It Short and Simple. Donnez-nous des exemples concrets de ce que cette chose fait et les ours polaires, ainsi que les utilisateurs, seront plus heureux.
