L’édito de GNU/Linux Magazine n°207 !

Ça y est les vacances sont terminées et vous voilà lancé, plein d’énergie, à la conquête d’un nouveau projet et pour cela vous aurez besoin de lui… ce framework qui devrait remplir tout ce dont vous avez besoin dans ce projet, ce framework qui vous fera gagner un temps précieux, celui pour lequel vous vous êtes mis à baver devant votre écran en vous disant « il me le faut ! ». Alors vous vous lancez, plein de fougue, dans l’installation de cet outil… mais bien entendu, il y a toujours un léger décalage entre la présentation du site web et la mise en pratique…

Souvent la page web est en totale adéquation avec la difficulté d’installation et de mise en œuvre : une seule page html contenant quatre lignes pour l’installation et au grand maximum une cinquantaine de lignes de documentation de l’API (quand on ne vous renvoie pas directement sur les sources). Dans ce cas, on sait à quoi s’attendre et généralement on ne se fait pas trop d’illusions quant au temps qu’il faudra passer/perdre pour effectuer quelques tests qui généralement conduiront à l’abandon du framework puisque l’absence de documentation le rend très difficilement utilisable.

Malheureusement, dans certains cas assez rares, on peut être en présence d’un projet particulièrement bien documenté, donnant accès à une description précise de l’API avec liens vers le code source et contenant de nombreux exemples sous la forme de tutoriels. Là il est normal d’être optimiste… mais lorsque l’on déchante, on tombe de bien plus haut ! Des éléments pouvant paraître anodins prennent des proportions gigantesques. Par exemple, si le projet requiert la dernière version de tel ou tel langage, non disponible dans le gestionnaire de paquets de votre distribution préférée, il va falloir l’installer. La documentation se bornera à cela : « Installez la dernière version du langage ». Le problème ici est que pour compiler un langage il faut disposer de certains outils et qu’il y a parfois de petites astuces de configuration à connaître ! Vous allez donc perdre deux jours (ou plus) avant même de pouvoir ne serait-ce que tenter d’installer le framework lui-même. Pourtant, dans la documentation cela semblait assez simple, la phrase était concise : « Installez la dernière version du langage »… (si les développeurs avaient pu le faire, ils auraient certainement ajouté « … et démxxxez-vous ! »). Ensuite, après bien des efforts, vous allez vouloir enfin tester le super exemple trouvé dans l’un des tutoriels de la documentation… et là encore il faudra y passer énormément de temps : on utilise des fonctions, des objets sans savoir exactement ce qu’ils font ni quels sont les paramètres à leur transmettre ! Certes l’exemple fonctionne, mais à quoi bon si l’on ne comprend pas ce que l’on fait et que l’on ne peut pas l’adapter ?

Écrire une documentation en apparence fournie ne suffit pas toujours, il faut également savoir expliquer, se mettre à la portée des utilisateurs qui ne vivent pas 24h/24 avec ce framework. C’est donc l’objet de l’un des articles que vous trouverez dans ce magazine et d’un autre côté, tant qu’il y aura ce genre de documentation il y aura du boulot pour GNU/Linux Magazine…;-)

Tristan Colombo

Laisser un commentaire