Nicolas Friedli

consultant web indépendant

Outils pour utilisateurs

Outils du site


documentation:start

Documentation technique

Est-il possible d’utiliser les méthodes de la documentation technique dans des contextes non techniques? Ma pratique du web dans le monde des institutions et des organisations me place souvent devant un contraste saisissant.

D’une part des outils web publient des documentations techniques remarquables; d’autre part les institutions et les organisations se contentent de présentations sommaires sur des sites vitrines.

Objectifs d'une documentation

Ma définition de travail:

Une documentation est un outil qui permet la découverte, l’apprentissage, la maîtrise autonome et la compréhension des enjeux de l’outil qu’elle documente.

Dans le détail, une documentation technique suit 4 lignes:

  • de la vulgarisation (pour susciter l’intérêt et entamer l’apprentissage)
  • de la didactique (pour commencer à utiliser l’outil)
  • de ressources (pour maîtriser complètement l’outil)
  • des discussions (pour comprendre les choix et leurs raisons)

Ces 4 lignes concourent au même objectif: la possibilité d’utiliser pleinement l’outil documenté de manière autonome.

La méthode Diátaxis

Les pistes précédentes sont inspirée du cadre de travail (framework) Diátaxis proposé par le spécialiste Daniele Procida. Selon cette méthode, les 4 axes sont:

  • tutorials (didacticiels)
  • how-to guides (guides «comment faire»)
  • technical reference (références techniques)
  • explanation (explications)

Diátaxis Framework (en anglais)

Une adaptation de ces axes à une documentation non techniques semble possible. C’est que je cherche à élaborer actuellement.

Ressources sur la documentation

Le site Write the Docs (en anglais) est une ressources inépuisable sur la documentation technique. Sa consultation régulière est vivement conseillée. En particulier, pour commencer:

Une analyse du site Write the Docs est aussi riche d’enseignements.


Voir aussi: Sphinx

documentation/start.txt · Dernière modification: 04.05.2022 par Nicolas Friedli