De quelle documentation les utilisateurs ont-ils vraiment besoin ?

L’extrait suivant provient de Wikipédia :

À la différence de la documentation sur le code, les documents utilisateurs sont généralement assez éloignés du code source du programme, et décrivent simplement comment il est employé.

Dans le cas d’une bibliothèque logicielle, les documents sur le code et les documents utilisateurs pourraient effectivement être couplés et cela vaut la peine de les regrouper, mais cela n’est pas toujours valable pour les applications en général.

La machine Lisp a suivi la tradition selon laquelle chaque élément de code avait un champ de documentation attaché. En relation avec les fortes capacités de recherche (basées sur une commande appropriée assimilée à Unix), et des sources en ligne, les utilisateurs de Lisp pouvaient consulter la documentation et reprendre la fonction associée directement dans leur propre code. Ce niveau de facilité est inconnu de systèmes présumés plus modernes.

Typiquement, la documentation utilisateurs décrit chaque caractéristique du programme, et les différentes étapes nécessaires pour l’appeler. Un bon document utilisateur peut aussi aller jusqu’à fournir une assistance minutieuse en ligne. Il est très important que les documents utilisateurs ne soient pas confus, et qu’ils soient à jour. Les documents utilisateurs n’ont pas besoin d’être structurés d’une façon particulière, mais il est très important qu’ils aient un index précis. La cohérence et la simplicité sont aussi deux qualités très précieuses. On considère que la documentation utilisateur constitue un contrat qui spécifie ce que le logiciel doit faire. Voir aussi Technical Writing.

Il y a trois grandes manières d’organiser la documentation utilisateur :

  1. Tutoriel: On considère qu’une approche par tutoriel est la plus utile pour un nouvel utilisateur. Dans cette méthode l’utilisateur est guidé à chaque étape d’accomplissement des tâches particulières.
  2. Thématique: Pour un utilisateur intermédiaire, on emploie généralement une approche thématique, dans laquelle les chapitres ou sections se concentrent sur un domaine d’intérêt particulier.
  3. Liste: Le type final de principe d’organisation est celui dans lequel les commandes ou les tâches sont simplement listées par ordre alphabétique, souvent via des indices croisés. Cette dernière approche est d’un intérêt très élevé pour des utilisateurs avancés qui connaissent exactement quelle sorte d’information ils recherchent. Un grief universellement exprimé par les utilisateurs au sujet de la documentation logicielle est qu’elle n’adopte que l’une de ces trois approches à l’exclusion des deux autres.

Dans le cas des micro-ordinateurs, il est fréquent de limiter la fourniture de documentation logicielle à l’aide en ligne, qui se limite à des informations de référence sur les commandes ou les lignes de menu. Le travail d’enseignement de nouveaux utilisateurs ou d’aide à des utilisateurs plus expérimentés à tirer le meilleur parti d’un programme est laissé à des publicateurs privés, à qui le développeur du logiciel donne une assistance significative.

Tiré de : wikipedia.org/wiki/Documentation_logicielle

 

Hmmm!

Bien, par où commencer ?

Nous avons dix ans de retard. Plus personne ne lit des tonnes de documentation. Si l’on parle de chapitres et de documents, cela signifie que la documentation est déconnectée.

« L’effort consistant à accompagner les nouveaux utilisateurs ou à aider les plus expérimentés à exploiter au mieux un programme revient aux éditeurs privés, souvent bien aidés par les développeurs logiciel. » Dans le passé et encore aujourd’hui, dans certaines entreprises, ils veulent être payés pour leur formation. Mais est-ce la bonne approche ?

Nous devons rattacher toutes ces formes d’information à une nouvelle stratégie de délivrance de l’information favorisant la satisfaction utilisateur.

 

Les utilisateurs ont besoin d’être guidés

Un guide, et non de l’aide. Si votre utilisateur a besoin d’aide, c’est que vous l’avez perdu. Vous devez savoir pour le type d’utilisateur pour lequel vous écrivez : débutant, expérimenté, expert. Cela dépendra de plusieurs facteurs, dont, entre autres :

  • le logiciel est-il nouveau ? (si oui est-il simple à prendre en main ?)
  • êtes-vous en train de changer les habitudes ?
  • remodelez-vous les règles établies ? (repenser un processus par exemple)
  • les utilisateurs doivent-ils être formés ?

Décider de comment guider les utilisateur fait partie de la conception de la stratégie éditoriale. Une fois définie, suivez-la. Une partie de l’information fournie peut afficher : « utilisation experte ».

 

Comment savoir ce dont les utilisateurs ont besoin ?

Vous devriez. Même si vous débutez, vous avez une idée de votre cible, n’est-ce pas ? Ensuite, au fur et à mesure, les retours utilisateurs et le support mettront en évidence les besoins.

 

Par où dois-je commencer ?

Couvrez les besoins basiques uniquement. Voyez ce qui est recommandé dans les méthodes agiles :

Oui, ceci s’applique à la documentation. On se réfère aux documents en utilisant la notion de topics.

Et à nouveau :