Améliorer la Documentation

La documentation du site Ubuntu-FR est publiée sous forme de wiki, un système de rédaction ouvert et collaboratif que chacun est libre de modifier. Il est rédigé sur une base volontaire, bénévole par les utilisateurs-mêmes d'Ubuntu et d'autres logiciels.

Comme pour tout site de type wiki, la qualité repose sur la responsabilité et le bon sens de chacun, bien qu'il existe un état d'esprit associé à la technique utilisé.

Évidemment, cette documentation ne peut pas être totalement parfaite. Il y a toujours place à l'amélioration. Mais comment participer à l'élaboration de cette documentation quand on n'a ni le temps, ni la patience, ni la facilité, ni la technique, ni les connaissances pour écrire un tutoriel ou un article ? De plus, il est vrai que la plupart des contributeurs à cette documentation sont des utilisateurs plus expérimentés, pour qui certaines manipulations semblent être "toutes naturelles", ce qui rend des documents moyennement clairs ou intuitifs.

Enfin, pour que le travail commun soit plus efficace des recommandations sont exprimées, et il est demandé de les suivre afin de tendre vers une documentation toujours plus claire et homogène.

Que faire pour simplifier la documentation, ou proposer des améliorations quand un article n'est pas clair ?

Il suffit de cliquer sur éditer cette page (dans l'encart actions en haut a gauche) pour avoir la possibilité de modifier une page existante.

Le bouton aperçu permet de visualiser les changements et permet de les retrouver (depuis son ordinateur seulement).

Le bouton enregistrer sauve la modification (sur le serveur) et la rend accessible à tous.

Pour se familiariser avec ce système le page bac à sable permet de faire des essais sans aucun risque.

Voici différentes façon de présenter à titre indicatif les bases éthiques sur lesquelles repose les mécanisme techniques (d'ubuntu, du site ubuntu-fr et plus précisément de cette documentation) :

• Un code de conduite (issue du site anglais) est induit par les principes d'ubuntu qui se rattachent notamment à la philosophie du même nom. (Voir aussi l'article Ubuntu (idéologie) sur wikipédia et une vidéo représentant ce concept, présente dans la distribution ubuntu et visible ici).

• Il ressort également de l'expérience commune quelques principes élémentaires relatifs à la documentation sous forme wiki :
  • Rester aussi simple que possible : Cette notice a comme ambition de pouvoir s'adresser à tous.
  • Distinguer les faits : Ce sont eux qui vont aider l'utilisateur. Un choix, une préférence, ou une recommandation sont du domaine des avis, Pour obtenir un fait il faut préciser selon qui.
  • Commencer par la bases : Ce qui est évidents est important. C'est la première marche indispensable pour les plus novices, mais aussi ce qui permet d'organiser facilement les choses plus complexes.

• Cette documentation peut aussi être représenté par des métaphores (pour imager autrement les principes précédents) :
  • C'est un pense bête communautaire : Il doit permettre à chacun de retrouver ce qui est utile pour lui, sans gêner ce qui est utile pour les autres.
  • C'est aussi un bagage pour un voyage vers l'inconnu : Les choses les plus utiles doivent rester les plus accessibles, mais il faut aussi prévoir de faire face à des situations qu'on ne connait pas encore.

• Suivre le modèle d'une page
• Aide à la syntaxe, pour savoir comment utiliser le langage de mise en forme de ce système wiki.
  • La page docuwiki expliquant la syntaxe
• playground Littéralement la salle de jeu avec des exemple de mise en forme.

La procédure choisie durant la réunion 2006 #3 pour notifier les contributeurs des améliorations à apporter est de modifier directement la page et d'indiquer aux endroits appropriées : "Ce passage n'est pas clair, il mérite révision". Les personnes inscrites suivant la page seraient avisées immédiatement de la modification, verraient en quoi elle consiste et pourraient effectuer les actions nécessaires. Toutefois, à l'heure actuelle, le système de notification des modifications par page ne semble pas fonctionner ; aussi cette technique devrait sans doute être 'laissée sur la glace', le temps que le tout se mette en place.

• Beaucoup d'articles sont signés par leur(s) auteur(s), en bas d'article. Beaucoup de contributeurs possèdent leur page de présentation personnelle où l'on peut les contacter directement (voir la liste des utilisateurs). Ainsi, contacter directement le contributeur en expliquant que son document X devrait être retravaillé dans telles sections car ceci ou cela est obscur (et de dire en quoi cela est obscur), c'est un moyen efficace pour voir ses remarques prises en compte et de voir apportées des modifications à l'article.
• Les plus téméraires voudront peut-être aussi s'abonner à la liste de diffusion des contributeurs du wiki (Coordination Wiki). Ils pourront ainsi discuter par courriel avec plusieurs contributeurs du wiki, leur présenter quels articles ils jugent difficiles et qui mériteraient une refonte. Bref, travailler en coopération avec ceux-là mêmes qui rédigent la documentation !
• Enfin, il est toujours possible de créer un fil de discussion dans le forum à propos d'un article précis. Quelques-uns des contributeurs au wiki passent aussi dans le forum, mais pas tous. Néanmoins, un fil de discussion aura le mérite d'attirer l'attention de personnes moins connaisseuses, de celles-là mêmes qui vont utiliser le wiki qui pourront réagir aux propositions, et peut-être aussi de futurs contributeurs ? Mais comme nous l'avons mentionné, tous les contributeurs ne passent pas dans le forum, donc il faudra aussi penser à les contacter pour qu'ils puissent appliquer les modifications nécessaires si personne ne s'en charge.¹⁾

La documentation d'Ubuntu-fr n'est peut-être pas toujours tout à fait claire, et c'est bien normal. Elle est en constante évolution et rédigée sur une base volontaire. La meilleure façon de la voir devenir meilleure est de la critiquer (de manière constructive) et d'informer de ses observations !