Wikisource

Utilisateur:Koreller/Documentation/Aide

< Utilisateur:Koreller‎ | Documentation

Cette page présente ma démarche d'amélioration générale de l'aide de Wikisource.

« S'il n'est pas documenté, il n'existe pas » — Mike Pope

« Une image vaut mille mots » — Adage populaire

"Cette documentation contient trop d'exemples !" n'a jamais dit de développeur.

Je me suis intéressé à la documentation des pages d'aides sur Wikisource après la refonte de la documentation des modèles, entre la transcription des œuvres de Maurice Courant, et avant la refonte des portails (j'ai fais une série de message dans les PDD de certains portails, le 10 octobre 2021, pour proposer des refontes).

Wikisource est un projet libre, et comme beaucoup de projet libre il n'y a pas de personne dédiées à la création et au maintien de la documentation. En étant usager de cette documentation, j'ai trouvé qu'il y avait des améliorations possible sur le fond et sur la forme. En effet je trouve la documentation de Wikisource parfois imprécise, elle nécessite à mon avis d'être amélioré.

L'espace de nom concerné par l'aide est principalement l'espace « Aide: », mais il peux aussi y avoir des choses dans l'espace « Wikisource: » (exemple : Wikisource:Partitions qui serait une bonne base pour structurer l'aide sur le sujet).

Sur Wikisource nous faisons dans l'espace de nom « Aide: » de la documentation utilisateur.

Veille sur les problèmes rencontrés modifier

Les problèmes sont souvent évoqués sur le Scriptorium (lieu d'échange privilégié de la communauté), il serait intéressant de voir les problèmes récurrents qui y apparaissent. Cette récurrence signifie que la documentation devrait peut-être (sûrement ?) être amélioré.

Construction des pages modifier

Les pages d'aides pourrait être découpées selon le modèle Concept/Tasks/References :

  • Concept : qui explique la notion (qui explique à qui s'adresse la page)
  • Task : qui est une forme de tutoriel pour l'utilisateur
  • References : qui est la documentation exhaustive de tout ce qui se fait, des usages, des contraintes, des façons de faire, des astuces connues, etc.

À voir si ses 3 éléments peuvent être pertinents sur une même page, ou si cela doit faire l'objet de pages séparées.

À mon avis, de manière générale les redites sont des bonnes choses pour les notions qui paraissent importantes sur la page d'aide (à mettre peut-être sous forme de petit encart ?).

Entête de page modifier

Le modèle {{Entête Aide}} doit permettre de répondre à certaines questions de base :

  • sur quel page se trouve l'utilisateur
  • de quoi parle la page
  • à qui s'adresse la page
  • …

Résumé modifier

Le résumé doit comporter à mon avis :

  • le contexte – à quoi sert la fonctionnalité
  • quand l’utilisateur doit-il l’utiliser (à voir pour ce point)
  • quelles sont les conséquences (le cas échéant) de son utilisation dans une mauvaise situation.

Se documenter sur la documentation modifier

Les documents qui explique la documentation sont nettement mieux en anglais, mais en français il existe des choses et j'en ai retenu plusieurs :

  • La documentation sur les projets libres est considérée comme mauvaise (car ce n'est pas attractif de faire de la documentation, il faut s'y connaître un minimum)
  • Un exemple bien expliqué vaux mieux que des longues descriptions.
  • Il faut penser à qui s'adresse la documentation, dans le cas de Wikisource : ce sont les nouveaux et les contributeurs plus expérimentées (qui chercherons une précision).
  • Avoir une cohérence dans les mots utilisés dans la documentation, si un verbe est associé à une action il est préférable d'avoir le même à chaque fois (éviter les synonymes !) pour éviter les incompréhensions.
  • 9 étapes est un nombre recommandé à ne pas dépasser pour de la documentation en mode tutoriel, si cela dépasse 9 étapes il serait préférable de diviser le tutoriel (cela pour éviter de perdre l'utilisateur)
  • Utiliser des titres concis et clair (que se soit à l'intérieur d'une page ou en recherche à travers la recherche dans wikisource)
  • Pensez à l'accessibilité (notamment pour la description des images avec des couleurs !)
  • Il faut se lancer dans la modification de la documentation, c'est aussi en faisant qu'on apprend !

Modèles modifier

Différents modèles permettent de mettre en forme les pages d'aide, en voici une liste

  • {{kbd}} pour la mise en forme de touche du clavier
  • {{Entête Aide}} pour l'entête d'aide, qui catégorise et permet d'afficher des messages clair.
  • {{En bref}}, récapitule les points essentiel d'une page ou d'une section.
  • {{En résumé}}, récapitule les points essentiel d'une page ou d'une section.
  • {{DD}}, modèle ergonomique pour la mise en regard d'une bonne et d'une mauvaise pratique.

Autres liens utiles pour les pages d'aides modifier

Note - Catégoriser l'espace « Aide: » modifier

Assassas77 à évoqué sur le Scriptorium une amélioration de la catégorisation des pages d'aides en Juin 2021 :

Assassas77 à commencé une structure pour la catégorisation

Travaux - post-it modifier

Comment documenter

Autres tâches

Récupérée de « https://fr.wikisource.org/w/index.php?title=Utilisateur:Koreller/Documentation/Aide&oldid=12244826 »