Les Raspberry Pi sont des petites bestioles (des mini pc en fait) assez prisées des Geeks de tout poils et des développeurs désireux d’apprendre à programmer sur de l’ARM. Grâce à leur faible coût et aux possibilités qu’offrent ces cartes (port USB, Ethernet etc.), elles permettent de mettre en œuvre pas mal de projets divers comme héberger un petit serveur, en faire un centre multimédia (elles peuvent décoder du Blue Ray full HD 1080p) et d’installer dessus, un grand nombre de distributions GNU/Linux.

XBMC est quant à lui un Mediacenter libre, ayant été à l’origine conçu pour la Xbox et porté ensuite sur GNU/linux, Windows et MAC OSX. Si ça vous intéresse vous pouvez faire un tour sur la page dédié de la doc Ubuntu, qui est très détaillée.

XBian est un projet qui vise à réunir le Raspberry Pi et XMBC, dans le but d’en faire un centre multimédia open source puissant et performant, un peu à la manière d’Openelec. La différence avec Openelec réside dans le fait que pour y parvenir, les développeurs du projet Xbian misent (et travaillent) sur une optimisation renforcée de ce mediacenter, grâce entre autres à l’introduction de noyaux compilés et de drivers spécifiquement adaptés au deux architectures. Je ne connaissait pas encore ce projet mais il m’a l’air vraiment très intéressant.

Une version 1.0 Beta de XBian a été publiée récemment et si vous êtes l’heureux possesseur d’un Raspberry Pi, vous pouvez déjà le télécharger et le déployer sur votre petite machine.

XBian 1.0 Beta 1 embarque entre autres :

• XBMC 12.2 Frodo par défaut (qui contient en prime pas mal d’améliorations pour les Raspberry Pi)
• La dernière version du noyau Linux
• Diverses corrections de bugs concernant xbian-config (servant à paramétrer XBian et XBMC)
• L’introduction du système de fichier btrfs (qui remplace Ext 4)
• Une réduction du temps de boot
• L’introduction par défaut de Superrepo (dont vous pouvez désormais installer tous les dépôts dans XBMC)

Et bien d’autres choses encore…

Si le projet XBian vous tente, vous pouvez en savoir plus en vous rendant sur le site officiel du projet et vous le procurer pour GNU/Linux, MS Windows et Mac OS X, en vous rendant sur la page de téléchargement.

Amusez-vous bien.

source

Original post of Noireaude.Votez pour ce billet sur Planet Libre.

Par goût personnel et par nécessité professionnelle, je rajoute progressivement le rôle d'administrateur système à mon métier de base qui est le développement de logiciels. Doté de bonnes bases UNIX et réseau, je découvre petit à petit les bon outils et les bonnes pratiques pour faire le job, le simplifier voire l'automatiser. Et parfois j'enverrais volontiers une caisse de bières à l'auteur d'un outil qui m'a sauvé plusieurs heures fastidieuses :-)

Dans cette série d'articles ma vie de sysadmin en semi-pro je parlerais épisodiquement de mes avancées et de mes découvertes dans le domaine de l'administration système.

Tout d'abord la console est ta seule amie. Sur ton PC de bureau, la console est un choix. Dans le monde des serveurs c'est un passage obligé car ils sont rarement installés avec une interface graphique et on les accède généralement par SSH. Les outils de base sont connus mais il faut apprendre à les maîtriser.

Ce qui propulse la console c'est un shell UNIX compatible Bourne Shell. Il y a plusieurs variantes : le Bourne Shell d'origine (sh), le Bourne Again Shell (bash), Korn Shell (ksh), Z Shell (zsh). Des experts sont capables de discuter de tel avantage de zsh par rapport à ksh. A mon niveau, maîtriser sh et Bash qui est le choix par défaut d'un grand nombre de systèmes GNU/Linux est le choix de la raison. On trouve beaucoup de littérature sur le sujet (le Bourne Shell existe depuis 1978 et le Bourne Again Shell depuis 1989 ), ma référence est le guide Advanced Bash-Scripting Guide sur le site du Linux Document Project. Ensuite il est bien sûr important de connaître les programmes en ligne de commande nécessaires pour les tâches de tous les jours : grep, find, locate, chmod, chown, cp, mv, mkdir, rm, rmdir, touch, top, kill, ps ... la liste est loin d'être exhaustive.

Un autre élément important est éditeur de texte en mode console. Il doit être polyvalent, léger, capable de traiter des fichiers de centaines de milliers de lignes. Deux candidats se détachent du peloton : Vim et Emacs. Les deux sont beaucoup plus que de simples éditeurs de texte. Ayant des rudiments de Vi depuis 20 ans, je me suis lancé à corps perdu dans l'apprentissage des fonctions avancées de Vim Que du bonheur ! Voici quelques liens :

• Vim FAQ
• Vimcasts - Vim podcasts
• Vundle - Vim Plugin manager

Quand on passe beaucoup de temps sur la console, on est à l'affut des manières de la rendre plus attractive et plus puissante

• Le prompt du shell par défaut est minimaliste. Pourquoi ne pas l'enrichir avec des informations utiles comme la charge processeur ou les infos de gestion de version (SVN, GIT) du répertoire courant ? C'est ce que propose le projet LiquidPrompt.
• Le choix des couleurs est important quand on passe beaucoup d'heures devant une console. Je ne parle pas de choisir une palette cool mais bien de préserver sa vue. J'ai fait le choix du schéma de couleur Solarized. Ca peut sembler un peu pâlot au début mais je me suis vité habitué et je l'utilise dans chaque programme où c'est possible. Dans le même registre, j'utilise le projet RedShift pour gérer la température des couleurs en fonction de l'heure de la journée et de votre emplacement géographique. Les deux premiers jours, on a l'impression que la luminosité est trop basse, ensuite on trouve cela normal. Et on se sent agressé quand on utilise une autre machine que la sienne.
• On se retrouve vite à ouvrir quantité de terminaux et à jongler entre eux. J'ai utilisé Terminator un temps puis j'ai pris confiance et j'ai eu besoin de multiplier les terminaux depuis une même session SSH et de lancer des traitements qui tournent en tâche de fond. Du coup, j'ai pris le temps d'apprendre Tmux et c'est un très bon investissement ! Un bon article pour démarrer est accessible ici.
• Quand on provisionne des serveurs régulièrement, il est intéressant de déployer sa configuration du shell, de l'éditeur de texte, ses outils afin de retrouver son environnement et ses habitudes. On peut installer ses fichiers manuellement depuis un point central comme son GitHub, ou mieux on peut carrément automatiser cette partie en utilisant un outil comme Fabric.

Le choix des outils présentés dans cet articles est personnel. Ce qui est intéressant, c'est la puissance de la console dans une utilisation quotidienne, la pléthore d'outils et le sentiment de maîtrise de ce qu'on fait.

Original post of Yannic Arnoux.Votez pour ce billet sur Planet Libre.

Nous avions achevé le précédent billet consacré à Desclicks en vous parlant de la location de machines à diverses associations et nous allons enchaîner dans la foulée avec une autre forme de mise à disposition, mais dans leur locaux cette fois-ci.

Desclicks propose en effet à ses membres de disposer d’une salle plutôt bien faite et très coquette, pourvue de pas mal de machines assurant une connexion internet gratuite pour les membres et au tarif très attractif de 50 cts de l’heure pour les non membres. Cela permet aux gens ayant très peu de moyens ou ayant besoin de conseils, de pouvoir disposer d’internet et d’effectuer ainsi différentes démarches en ligne si besoin. Pour de la recherche d’emploi par exemple.

J’ai bien aimé cette petite machine d’ailleurs :

Mais le reste n’est pas mal non plus :

Là aussi l’ouverture est de mise et si la plus part des machines tournent sous GNU/Linux, vous y trouverez quand même quelques machines sous Windows afin de n’exclure personne. Si les jeunes s’adaptent vite ce n’est pas toujours le cas des personnes âgées, qui bien souvent ont besoin d’un environnement qu’ils maîtrisent « bien ». Comme pour le reste en revanche, les machines sous Windows ne contiennent que des logiciels Libres en applications courantes (navigateur web, messagerie, bureautique etc…).

Vous trouverez en prime de la lecture très instructive :

Et vous pourrez même en emporter (j’aurais bien pioché dans le tas mais je n’ai pas osé) :

Formation et initiations :

Les habitudes étant faites pour être changées (même pour nos papis et mamies), Desclicks propose également un panel de formations ou d’initiations à bas coûts dédiés au Séniors. Ceux-ci sont collectifs et concernent des actions qui peuvent nous paraître simples mais qui peuvent poser des problème aux personnes plus âgées. Elles peuvent concerner en vrac le maniement de la souris, la découverte d’internet, l’apprentissage des courrier électroniques (e-mails) et bien d’autres choses encore.

Les formations sont dispensées à des petits groupes, se déroulent sur trois cycles et sur une période d’environ 6 semaines (à raison de 2 h 30 par semaine). ici aussi les tarifs sont très attractifs afin de permettre à tout le monde d’en profiter. De plus elles se terminent par une petite pause boisson/repas, qui favorise l’émergence du lien social (ce qui manque souvent aux personnes âgées).

D’autres formations s’adressent à des gens voulant approfondir leur connaissances dans le domaine de la Photo par exemple et (ou) peuvent être dispensées de manière individuelle (sur demande) dans des domaines plus spécifiques, modélisation 3d, base de données, de création de site internet, de blog, programmation etc etc…

Une fois encore nous constatons que le spectre d’intervention de Desclicks est très large, bien loin d’être figé et reste orienté sur la notion de communauté et de logiciel Libre.

En Vrac :

Desclicks dispense également des conseils d’achat pour du matériel neuf, dans le but d’assurer une certaine cohérence d’achat pour les gens qui ne s’y connaissent pas (ou très peu). Cela leur permet d’acheter une machine adaptée à leur besoins sans prendre le risque de se faire refourguer n’importe quoi , ce qui est assez souvent le cas quand on ne s’y connait pas. Cela dit selon Philippe les gens sont parfois têtus et ne suivent pas toujours leur conseils. Je n’en doute pas hi hi…

Et nous finirons ce tour d’horizon (pris par le temps ce jour-là) par signaler que Desclicks propose diverses opérations de maintenance et d’installations pour les membres et intervient lors d’évènements divers. Ils organisent des réunions diverses et nous leur devons une participation active au RMLL de Strasbourg ayant eues lieu en 2011.

Conclusion :

Desclicks est une association qui gagne à être connue, mais qui comme toutes les associations a des besoins spécifiques. Desclicks aurait besoin de deux salariés à temps partiels :

• Un administratif
• Et un technicien

Pour le reste c’est assez facile et si on veut résumer la chose joyeusement, il leur faut des bras et des sous !!!

Cette interviews c’est terminée comme elle a commencé à savoir cool et dans la bonne humeur. Nous sommes néanmoins partis délestés de 10 € (le prix d’une année de cotisation), car bien entendu nous avons souhaité adhérer de ce pas à cette association qui vaut son pesant d’or.

Nous remercions les bénévoles de Desclicks pour l’investissement dont ils font preuve au quotidien en faveur du logiciel libre et de la communauté en général. Et nous les remercions chaleureusement pour leur accueil sympathique et pour nous avoir ouvert leur portes pour notre première interview.

• Si vous habitez Strasbourg ou ses alentours et que vous souhaitez vous impliquer dans la communauté du Libre.
• Si vous souhaitez simplement en savoir plus à ce sujet ou rencontrer des gens partageant votre passion.

Sachez que Desclicks est là et que nous vous conseillons très fortement d’y faire un tour. Vous y trouverez des gens chaleureux et passionnés, comme on les aime.

Vous pouvez bien entendu en savoir plus en vous rendant sur le Site Officiel de l’Association Desclicks (vous nous y croiserez peut-être).

Pour ceux que ça intéresse nous vous laissons également les horaires d’ouverture et les coordonnées de Desclicks :

Horaires d’ouverture :

• lundi : 14h – 18h
• Mardi : 18h – 21h
• Mercredi : 14H – 19H
• Jeudi : 16h – 19h
• vendredi : 14h – 18h
• Samedi : 14h – 18h

Adresse et numéro de téléphone (attention l’entrée est bien planquée) :

Desclicks L’informatique Solidaire
3 rue saint Paul
67300 Schiltigheim
Téléphone : 03 88 83 64 10

Amusez-vous bien et peut-être à bientôt chez Desclicks.

Original post of Noireaude.Votez pour ce billet sur Planet Libre.

 

Nous vous avions parlé de notre nouveau projet dans ce billet et chose promise chose due, le premier billet arrive.

Si j’avais encore eu un doute sur l’utilité de ce genre de billets (ce qui n’est pas le cas), cette première interview m’aurait rassuré. Je suis arrivé (avec un peu de mal) devant un portail anodin et bien planqué, qui ne laissait rien présager de ce que j’allais trouver derrière ce dernier.

Pour la petite histoire je suis passé devant des centaines de fois (habitant à moins de 800 mètres de là), sans jamais me douter qu’une telle association existait à juste côté de chez moi et sans savoir ce que je loupais. Ces billets ne seront donc pas inutiles.

Nous allons vous parler de l’association Desclicks dans ce billet, qui comme vous pourrez le constater intervient dans une sphère de domaines assez large et utile, avec en toile de fond bien entendu, le logiciel Libre.

On relèvera au passage la présence de Régis (très concentré) à la transcription. Quel bosseur ! :

Nous avons été reçus de manière vraiment très sympathique par Philippe, un bénévole de l’association qui est également avec Damien (absent pour cause d’angine ce jour-là), l’un des membres fondateurs initiaux de Desclicks.

Philippe bénévole et membre fondateur de Desclicks (très beau tee-shirt) :

Desclicks est une association fondée en 2005 qui propose une large gamme de services et qui compte à l’heure actuelle 3 salariés en contrats aidés à temps partiels. Elle agit en étroite collaboration avec plusieurs intervenants et on relèvera que celle-ci a bénéficié de subventions provenant du Fond Social Européen (F.S.E), qu’elle occupe des locaux mis à disposition par la mairie de Schiltigheim et qu’elle dispose d’un soutien très fort de la C.U.S (Communauté Urbaine de Strasbourg), qui adhère pleinement à ses idées.

Collecte et recyclage :

Comme je l’ai dit plus haut Desclicks à un large spectre d’intervention et l’un de ses objectifs consiste à collecter du matériel informatique, afin de le recycler selon une démarche que nous pourrions qualifier d’éco-comportementale. Cette démarche est éco-comportementale dans le sens où elle n’a pas simplement pour but de recycler les matériaux pour en faire des déchets « propres », mais plutôt de reconditionner des composants (ou des machines) encore utilisables, afin d’en prolonger la durée de vie et donc, de limiter la quantité de ces déchets.

Ces machines sont ensuite équipées pour la plus part de logiciels Libres et cédées à des prix allant de 50 à 150 euros, permettant à des gens disposant d’un petit budget ou de connaissances limitées, de pouvoir s’équiper à un prix raisonnable tout en pouvant disposer de précieux conseils. Ceci est en parfaite cohésion avec les directives Européennes dont certaines visent à prolonger la durée de vie du matériel, cela réduit la fracture numérique, renforce le lien social et s’inscrit dans une démarche de développement durable. Les financements Européens de Desclick découlent d’ailleurs en partie de cette action.

Ceci peut être également vu (et un large sourire narquois a envahi tous les visages à l’évocation de cet argument), comme un vecteur de désinfestation Windowsienne).

Nous avons demandé à Philippe si les entreprises du coin jouaient le jeux et selon lui c’est le cas. Il nous a cité des noms tels que la Caisse d’Épargne qui selon lui est « LE » donateur historique, mais également des noms connus comme Cap Gemini, France3, In Extenso, la Banque Populaire, Oth Est et bien entendu comme souvent, des donateurs souhaitant rester anonymes que nous ne citerons donc pas.

Nous pouvons voir ici Sébastien (un autre bénévole) en plein boulot :

Et une petite partie de la tanière où résident les dons en attente de revente ou de remise en état :

Le volet install Party :

En coordination avec le LUG (Linux Users Group’s) de Strasbourg, Desclicks participe également à des soirées « Install Party » en fournissant leur locaux et des machines spécialement dédiées à cette usage.

Si vous habitez notre belle ville de Strasbourg, les membres du LUG sont présents dans les locaux de Desclicks pour des Install-parties, tous les derniers Mardis du mois, de 18h30 à 22h30. N’hésitez pas à vous y rendre avec votre machine si vous souhaitez faire le grand saut dans le monde du Libre.

La mise à disposition de matériel :

Depuis 2 ans et demi environ Desclicks propose également la location de machines pour une somme modique, à des fin de recherche d’emploi et ou d’apprentissage. Une quarantaine de machines sont d’ores et déjà présentes dans diverses associations, avec bien entendu une politique tarifaire favorisant le Libre. Nous avons vraiment été sensibles à cette démarche car nous l’avons trouvé très équitable. Même si la politique tarifaire est différente en fonction de l’OS disponible sur ces machines (proprio ou non), la différence n’est pas énorme, nous dirons même plutôt symbolique. Si le but est encore de promouvoir le libre ici, la volonté première reste de n’exclure personne.

Nous ne sommes donc pas devant des gens buttés et fermés d’esprit que nous pourrions qualifier « d’intégristes ». Ils ont parfaitement intégré le fait que tout le monde n’est peut-être pas encore prêt pour une raison ou une autre à franchir le pas et même si le but est d’inciter les gens à « libérer » leur informatique, ils ne les forcent pas pour autant.

L’autre point que j’ai aimé dans cette démarche, c’est que les machines fournies avec un OS propriétaire sont exclusivement équipées de logiciels libres. C’est pour moi un point très important voir fondamental.

Étant un ancien Windowsien (eh oui), si on m’avait mis un GNU/Linux tout de suite en me disant que c’était génial (et ça l’est), il y a de fortes chances pour qu’au premier problème je sois retourné illico sous Windows avec une mauvais impression et la ferme intention de ne plus en bouger.

Mon cheminement personnel a commencé par l’installation et l’utilisation de logiciels libres sous Windows, essentiellement glanés sur Framasoft. Ce n’est qu’après une longue période passée à en apprendre plus sur ces derniers et leur philosophie que j’ai franchi le pas pour de bon. Cela n’a pas été facile mais le fait d’avoir eu le temps de goûter à leur puissance sans soucis et sur une plate-forme que je maîtrisais bien (Windows à l’époque), m’a paradoxalement donné l’envie et la volonté nécessaire de la quitter pour de bon.

Il est donc très important de laisser le choix au gens et d’y aller progressivement car dans les faits, les beaux discours moralisateurs ne servent à strictement à rien si le premier contact est mauvais.

Nous allons finir ici la première partie de cette interview et vous donner rendez-vous pour la suite (et fin) de cet entretien, dans un second billet.

À tout de suite…

Original post of Noireaude.Votez pour ce billet sur Planet Libre.

Qu’il s’agisse de son code ou de son utilisation, la faiblesse de la documentation d’un logiciel libre est souvent montrée du doigt.

Voici, selon Andy Lester, 13 défauts ou lacunes communément rencontrés, qui sont autant d’écueils que l’on peut contourner avec un minimum d’efforts aujourd’hui pour gagner demain un temps précieux.

13 choses que les gens détestent sur vos documentations open source

13 Things People Hate about Your Open Source Docs

Andy Lester - 10 janvier 2013 - SmartBear Blog
(Traduction : Lamessen, calou, Shanx, sinma, Asta + anonymes)

La plupart des développeurs open source aiment penser à la qualité du logiciel qu’ils développent, mais la qualité de la documentation est souvent laissée de côté. Il est rare de voir vanter la documentation d’un projet, et pourtant elle a un impact direct sur sa réussite. Sans une bonne documentation, les utilisateurs n’utiliseront pas votre projet, ou ils n’y prendront pas de plaisir. Les utilisateurs comblés sont ceux qui diffusent des infos à propos de votre projet – ce qu’ils ne font qu’après avoir compris comment il fonctionne. Et ils apprennent cela à partir de la documentation du projet.

Malgré tout, de trop nombreux projets ont une documentation décevante. Et cela peut être décevant de plusieurs manières.

Les exemples que je donne ci-dessous sont purement arbitraires, je ne veux pas cibler un projet en particulier. Ce sont seulement ceux que j’ai utilisés récemment, cela ne veut pas dire qu’ils représentent les pires atrocités. Chaque projet a commis au moins quelques-uns de ces péchés. Que vous soyez utilisateur ou développeur, à vous d’évaluer à quel point votre logiciel préféré est ou non coupable, et comment vous pouvez aider à y remédier le cas échéant.

1. Le manque d’une bonne introduction ou d’un README/LISEZ-MOI

Le README/LISEZ-MOI est la première impression que les utilisateurs potentiels ont de votre projet. Si le projet est sur GitHub, le README/LISEZ-MOI est automatiquement affiché sur la page d’accueil du projet. Si vous l’avez mal rédigé, ils peuvent ne jamais revenir.

Vous voulez capter l’attention du lecteur et l’encourager à continuer la découverte de votre projet ? Le README/LISEZ-MOI devrait alors au moins expliquer :

• ce que le projet fait
• pour qui il est fait
• sur quel matériel ou plateforme il tourne
• toutes les dépendances majeures, comme « Requiert Python 2.6 et libxml »
• comment l’installer, ou un accompagnement de chaque étape à la suivante.

Tout cela doit pouvoir être compris par quelqu’un qui n’a jamais entendu parler de votre projet, et peut-être même jamais imaginé un projet pouvant s’en rapprocher. Si le projet possède un module calculant la distance de Levenshtein, ne partez pas du principe que n’importe qui lisant votre README/LISEZ-MOI sait ce que c’est. Expliquez que la distance de Levenshtein est utilisée pour comparer deux chaînes de caractères, et ajoutez quelques renvois vers des explications plus poussées pour celui qui aimerait approfondir le sujet.

Ne décrivez pas votre projet par rapport à un autre projet, comme « NumberDoodle est comme BongoCalc, mais meilleur ! » Ça n’est d’aucune aide pour quelqu’un qui n’a jamais entendu parlé de BongoCalc.

2. La documentation non disponible en ligne

Bien que je n’ai pas lu d’études à ce sujet, je serais prêt à parier que 90% des recherches de documentation sont faites avec Google et un navigateur sur Internet. La documentation de votre projet doit être en ligne, et disponible. Partant de là, il serait embarrassant que la documentation de mon propre projet, ack, ne soit pas disponible à l’endroit où la majorité des gens vont la chercher. Mon hypothèse est basée sur ma propre expérience, à savoir que si je veux connaître le fonctionnement d’un outil en ligne de commande, je vais vérifier sa page man.

Comment je m’en suis aperçu ? Les utilisateurs m’écrivaient pour me poser des questions dont les réponses se trouvaient dans la FAQ. Ce qui m’a ennuyé : ils ne lisaient pas ma FAQ. Il se trouve qu’ils avaient cherché sur le site internet, mais je n’avais pas mis la FAQ à cet endroit. C’est une erreur facile à faire. Je suis proche du projet et je n’ai jamais eu besoin d’utiliser moi-même la FAQ, je n’avais donc pas remarqué qu’elle n’était pas présente en ligne. Beaucoup de problèmes sont dus à ce piège : les auteurs ne se mettent pas à la place des utilisateurs.

3. La documentation disponible uniquement en ligne

Le revers de ce problème est d’avoir la documentation disponible uniquement en ligne. Certains projets ne distribuent pas la documentation avec les livrables du projet, ou incluent une version médiocre de la documentation.

Le moteur de recherche Solr, par exemple, a un excellent wiki qui sert à la documentation du projet. Malheureusement, la documentation liée au téléchargement comporte 2200 pages de Javadoc d’API auto-générées. Au final, la seule documentation pour l’utilisateur est une unique page de tutoriel.

Le langage PHP n’est distribué avec aucune documentation. Si vous voulez la documentation, vous devez aller sur une page séparée pour les obtenir. Pire, seule la documentation du cœur est disponible au téléchargement, sans les annotations utiles des utilisateurs (voir « Ne pas accepter les remarques des utilisateurs » plus bas), et ce n’est pas le même format facile à parcourir que celui qui est disponible en ligne.

Les projets open source ne peuvent pas supposer que les utilisateurs ont accès à Internet quand ils ont besoin de la documentation. Le mode avion existe toujours. De toute façon, vous ne souhaitez pas que l’utilisateur dépende uniquement du fait que votre site web est disponible ou non. Au moins à deux reprises durant les derniers mois, le wiki de Solr était indisponible au beau milieu de ma journée de travail alors que je recherchais des informations sur un problème de configuration épineux.

Un projet qui fait les choses bien est Perl et son dépôt de module CPAN. La documentation pour chaque module est disponible soit à search.cpan.org ou metacpan.org dans un format hypertexte facile à lire. Pour la consultation hors-ligne, la documentation de chaque module est intégrée dans le code lui-même, et quand le module est installé sur le système d’un utilisateur, la documentation locale est créée sous forme de pages man. Les utilisateurs peuvent aussi utiliser « perldoc Module::Name » pour obtenir la documentation depuis le shell. En ligne ou hors-ligne : c’est votre choix.

4. La documentation non installée avec le paquet

Ce problème est généralement une erreur des paquageurs, pas des auteurs du projet. Par exemple, sur Ubuntu Linux, la documentation du langage Perl est séparée, ce sont des paquets optionnels pour le langage lui-même. L’utilisateur doit savoir qu’il doit explicitement installer la documentation de la même façon que le langage principal ou il n’y aura pas accès quand il en aura besoin. Ce compromis de quelques mégabites d’espace disque au détriment de la documentation à portée de main de l’utilisateur dessert tout le monde.

5. Le manque de captures d’écran

Il n’y a pas de meilleur moyen d’obtenir l’attention potentielle d’un utilisateur, ou d’illustrer un usage correct, qu’avec des captures d’écran judicieuses. Une image vaut mieux qu’un long discours, c’est encore plus important sur Internet parce que vous ne pouvez obtenir d’un lecteur de lire plus de quelques centaines de mots en tout.

Les captures d’écran accompagnant le texte sont inestimables pour guider l’utilisateur voulant faire les choses au mieux. Une capture d’écran lui permet de comparer visuellement ses résultats à ceux de la documentation et va le rassurer d’avoir exécutée la tâche correctement ou l’aidera à trouver facilement ce qui ne va pas.

Il est de plus en plus commun de trouver des vidéos sur le site internet d’un projet pour en donner un aperçu, et c’est génial. Tout autant que le fait d’avoir une vidéo pour chaque étape d’un processus complexe. Le projet Plone, par exemple, a un site entier dédié aux tutoriels vidéos. Cependant, les vidéos ne peuvent pas remplacer les captures d’écran. Un utilisateur veut voir rapidement l’allure des captures d’écran sans s’arrêter devant une vidéo. Les vidéos n’apparaissent également pas dans une recherche Google Image, à l’inverse des captures d’écran.

6. Le manque d’exemples réalistes

Pour les projets basés sur du code, l’analogue des captures d’écran sont de bons et solides exemples du code en action. Ces exemples ne devraient pas être abstraits, mais directement issus du monde réel. Ne créez pas d’exemples bateaux plein de « nom de la démo ici » et lorem ipsum. Prenez le temps de créer des exemples signifiants avec une histoire d’utilisateur qui représente la façon dont votre logiciel résout un problème.

Il y a de bonnes raisons de vous embêter avec des problèmes de maths en classe. Ils permettent d’appliquer ce que vous avez appris.

Disons que j’ai écrit un module d’un robot Web, et que j’explique la méthode follow_link. Je pourrais montrer la définition de la méthode ainsi :

$mech->follow_link( text_regex => $regex_object, n => $link_index );

Mais admirez à quel point cela devient évident en ajoutant de la réalité dans l’exemple.

# Suit le 2e lien où la chaîne de caractères « download » apparait
$mech->follow_link( text_regex => qr/download/, n => 2 );

Les noms des variables $regex_object et $link_index sont maintenant compréhensibles par le lecteur.

Bien entendu, vos exemples ne doivent pas être aussi brefs. Comme Rich Bowen du projet Apache le souligne, « Un exemple correct, fonctionnel, testé et commenté l’emporte sur une page de prose, à chaque fois. »

Montrez autant que possible. L’espace n’est pas cher. Créez une section dédiée aux exemples dans la documentation, ou même un livre de cuisine. Demandez aux utilisateurs d’envoyer du code qui fonctionne, et publiez leurs meilleurs exemples.

7. Liens et références inadéquats

Vous avez les hyperliens. Utilisez-les.

Ne pensez pas, parce que quelque chose est expliquée dans une certaine partie de la documentation, que le lecteur a déjà lu cette partie, ou bien qu’il sait où elle se trouve. Ne vous contentez pas de signaler que cette partie du code manipule des objets frobbitz. Expliquez brièvement lors du premier usage de ce terme ce qu’est un objet frobbitz, ou donnez le lien vers la section du manuel l’expliquant. Encore mieux, faites les deux !

8. Oublier les nouveaux utilisateurs

Il arrive trop souvent que l’écriture de la documentation soit rédigée à partir du point de vue de son auteur, alors que es nouveaux utilisateurs ont besoin de documentation d’introduction pour les aider.

L’introduction devrait être une page séparée de la documentation, idéalement avec des exemples qui permettent à l’utilisateur de réussir quelques manipulations avec le logiciel. Pensez à l’excitation que vous ressentez quand vous commencez à jouer avec un nouveau logiciel et qu’il vous permet de faire quelque chose de cool. Faites que ça arrive aux nouveaux utilisateurs également.

Par exemple, un package graphique pourrait présenter une série de captures d’écran qui montrent comment ajouter des données dans un fichier, comment faire intervenir le grapheur, et ensuite montrer les graphes obtenus. Une bibliothèque de codes pourrait montrer quelques exemples d’appels à la bibliothèque, et montrer le résultat obtenu. Pensez simplicité. Offrez une victoire facile. Le texte devrait introduire les termes aux endroits appropriés, avec des liens vers une documentation plus détaillée sur le long terme.

Un document de démarrage séparé donne à l’utilisateur une compréhension rapide du logiciel. Il garde aussi les explications d’introduction en dehors de la partie principale de votre documentation.

9. Ne pas écouter les utilisateurs

Les développeurs doivent écouter les utilisateurs de la documentation. La chose évidente est d’écouter les suggestions et requêtes des personne qui utilisent activement votre logiciel. Quand un utilisateur prend le temps d’écrire un mail ou de poster quelque chose comme « ça aurait pu m’aider à mieux installer le programme s’il y avait eu une explication ou des liens au sujet des pilotes de la base de données », prenez ce message au sérieux. Pour chaque utilisateur vous envoyant un mail pour un problème, vous devez vous attendre à ce que dix utilisateurs silencieux aient le même problème.

Il est important d’écouter les problèmes des utilisateurs et d’en chercher les causes. S’ils ont souvent des problèmes pour effectuer des mises à jour groupées de bases de données, la première chose à faire est d’ajouter une question à la FAQ (vous avez bien une FAQ, n’est-ce pas ?) qui traite de ces questions-là. Cependant, la question peut aussi indiquer que la section traitant des mises à jour de base de données n’est pas assez claire. Ou peut-être qu’il n’y a pas de référence à cette section depuis la vue d’ensemble introductive du document, avec pour conséquence que vos utilisateurs ne pensent jamais à lire le reste du manuel.

En plus d’aider plus de gens à découvrir à quel point votre projet est utile, ça diminuera aussi la frustration de la communauté déjà existante. Si votre liste de diffusion, forum ou canal IRC est remplie de personnes qui posent toutes les mêmes questions idiotes (ou pas si idiotes) au point que tout le monde devient lassé d’y répondre, sachez reconnaître que ce sont des questions récurrents pour la FAQ, et mettre les réponses à un endroit facile à trouver aidera tout le monde à se concentrer sur des choses plus amusantes.

Gardez aussi un œil sur les questions des forums externes. Consultez les sites comme StackOverflow régulièrement, et placez une Google Alert sur votre nom de projet pour être maintenu au courant des discussions concernant votre projet sur Internet.

10. Ne pas accepter les entrées des utilisateurs

Si votre projet a une base d’utilisateur assez grande, il peut être judicieux d’incorporer les commentaires des utilisateurs directement dans la documentation. Le meilleur exemple que j’ai pu voir est celui donné par PHP. Chaque page de la documentation permet aux utilisateurs authentifiés d’ajouter des commentaires sur la page, aidant ainsi à clarifier certains points ou ajoutant des exemples qui ne sont pas dans la documentation principale. L’équipe PHP laisse aussi le choix au lecteur de lire la doc avec ou sans les commentaires des autres utilisateurs.

Aussi pratique cela soit-il, cela nécessite de la maintenance. Les commentaires doivent être éliminés de temps en temps pour éviter la prolifération. Par exemple, la page de la documentation PHP sur comment lancer PHP depuis la ligne de commande inclut 43 commentaires d’utilisateurs qui remontent à 2001. Les commentaires écrasent la documentation principale. Les commentaires devraient être archivés ou supprimés, tout en incluant les points les plus importants dans la documentation principale.

Un wiki est également une bonne approche. Cependant, si votre wiki ne permet pas à l’utilisateur de télécharger toutes les pages en une seule grosse archive (cs. point n°3 ci-dessus), alors vos utilisateurs sont à la merci de votre connexion internet et du serveur hébergeant le projet.

11. Impossibilité de voir ce que fait le logiciel sans l’installer

Au minimum, chaque projet de logiciel nécessite une liste de fonctionnalités et une page de captures d’écran pour permettre au potentiel utilisateur intéressé de savoir pourquoi il devrait l’essayer. Aidez l’utilisateur, comparant les différents paquets à utiliser, à voir pourquoi cela vaut la peine de prendre le temps de le télécharger et de l’installer.

Les images sont un bon moyen de faire cela. Votre projet devrait avoir une page « Captures d’écran » qui montre des exemples de l’outil en action (cf. point n°5 ci-dessus). Si votre projet se résume uniquement à du code, comme une librairie, alors il devrait y avoir une page d’exemples montrant ce code utilisant le projet.

12. S’appuyer sur la technologie pour votre rédaction

Trop souvent, les auteurs de logiciels utilisent des systèmes de documentation automatisés pour faire leur travail. Ce système automatisé rend les choses plus facile à maintenir, mais il ne supprime pas la nécessité d’un travail d’écriture humain.

Le pire des cas concerne le changelog, qui n’est rien de plus qu’un dump des messages de commit du système de gestion de version, mais sans un résumé qui l’explique. Un changelog devrait lister les nouvelles fonctionnalités, les problèmes résolus et les incompatibilités potentielles. Sa cible est l’utilisateur final. Un log de commit est pratique et simple à générer pour les personnes travaillant sur le projet, mais ce n’est pas ce dont l’utilisateur a besoin.

Jetez un œil à cette page de la documentation de Solarium, une interface PHP pour le moteur de recherche Solr. Tout d’abord, l’avertisemment prend la moitié supérieure de l’écran, ne donnant aucune information au lecteur. Ensuite, il n’y a vraiment rien de véritablement descriptif sur la page que la liste des noms de fonctions. Il n’y a aucune explication sur les différentes méthodes, ni de liens indiquant où trouver l’explication. Les pages générées automatiquement sont jolies, et elles pourraient ressembler à de la documentation, mais elles n’en sont pas.

13. Arrogance et hostilité vis-à-vis de l’utilisateur

L’attitude du type RTFM (Read The Freaking Manual) est mauvaise pour votre projet et votre documentation.

C’est le summum de l’arrogance que de croire que tous les problèmes qui ont trait au fait que quelqu’un ne sache pas utiliser votre logiciel sont de la faute de l’utilisateur.

Même s’il est probablement vrai que les utilisateurs peuvent trouver leurs réponses dans votre documentation mais ne le font pas, il est stupide de penser que c’est la faute de l’utilisateur. Peut-être votre documentation est-elle mal écrite, ou difficile à lire, ou présente mal à l’écran. Peut-être avez-vous besoin d’améliorer la section « Mise en route » (lien #8 ci-dessus) qui explique ce que le logiciel a pour but de faire. Peut-être que certaines parties d’information nécessitent d’être répétées à de multiples endroits de la documentation.

N’oubliez pas que les nouveaux utilisateurs de votre logiciel peuvent arriver sur votre projet sans rien n’en savoir. Votre documentation doit faire de son mieux pour s’assurer que cette ignorance soit facilement résolue.

Synthèse

Je suis sûr que vous avez déjà eu affaire à quelques-uns de ces problèmes listés ci-dessous, et peut-être que pour d’autres vous n’y avez pas pensé. Faites-nous connaître les problèmes que vous avez rencontrés dans les commentaires ci-dessous, sachant qu’il ne s’agit pas de pointer du doigt certains projets en particulier.

Surtout, j’espère que si vous reconnaissez un problème dans la documentation de vos projets, vous prendrez la peine d’améliorer la situation. Heureusement, améliorer la documentation est une manière idéale de faire participer les nouveaux arrivants dans votre projet. On me demande souvent : « Comment puis-je commencer dans l’open source », et je recommande des améliorations dans la documentation comme une bonne manière de commencer.

Faites-en sorte que ce soit aussi facile que possible, pour les novices comme les plus anciens, de savoir où il est nécessaire de travailler la documentation. Créez une liste des tâches, par exemple dans votre système de suivi des bogues, qui explique ce qui a besoin d’être amélioré. Soyez précis dans ce que sont vos besoins. Ne vous contentez pas de dire que vous avez besoin d’exemples, sans plus de précision. Créez des tâches spécifiques, comme « ajoutez un code d’exemple sur le fonctionnement de la tâche X », « ajouter une capture d’écran du générateur de rapports » ou « ajouter des informations de dépendances au fichier README/LISEZ-MOI ». Les contributeurs souhaitent aider mais trop souvent ils ne savent pas par où commencer.

La documentation n’est pas la partie la plus glamour d’un projet open source, et pour la plupart d’entre nous ce n’est pas amusant. Mais sans une bonne documentation, les utilisateurs ne sont pas servis comme ils pourraient l’être, et votre projet en souffrira sur le long terme.

Crédit photo : Rosalux Stiftung (Creative Commons By)

Original post of Framablog.Votez pour ce billet sur Planet Libre.