Conférence de Matthias Dugué
Voir les slides
Voir la vidéo

La véritable histoire de toute documentation c’est que personne ne sait comment bien faire et que c’est toujours le bazar à un moment.

Cette méthode peut s’appliquer à tous ce qui est commun :

  • le code
  • les projets
  • les plateformes
  • les outils

Le manuel

Personne n’est obligé d’utiliser votre produit, il faut donc une documentation minimale avec :

  • les pré-requis
  • le démarrage rapide
  • la licence
  • la contributions
  • le support

Le readme

La documentation basique c’est le readme. Mais elle apporte un problème de maintenance dès lors qu’il y a trop d’informations et un risque important de décorrélation.

Le wiki

Le wiki apporte une séparation des contenus et une cohésion de l’ensemble de la documentation. Cependant il reste difficilement maintenable.

La doc en tant que projet

Il existe quelques soucis pour gérer la curation des contenus, leurs obsolescence et la contribution.

Il ne faut pas s’attacher à l’outil mais se poser les bonnes questions :

  • qui accède aux contenus ?
  • comment rechercher l’information ?
  • pourquoi contribuer ?

S’il existe une communauté, il est possible de s’appuyer sur eux pour tester la documentation.

Le guide

On entend beaucoup : Read The Fucking Manual (RTFM) seulement c’est tout sauf bienveillant et précis.

Les personnes qui accède à la documentation recherchent :

  • un élément précis
  • une thématique dédié
  • apprendre

Dans la documentation il faut mettre les pages de docs, le sommaire, les chapitres et les tags.

Quels contenus ?

Il faut maintenir 4 documentations pour bien faire.

1 – Readme / Concepts

Elles sont focalisée sur l’apprentissage et donnent un point de départ, un contexte. Par ex :

  • Démarrer avec la plateforme
  • Utiliser le mode d’internationalisation
  • Exécuter les tests

2 – How To

Il est orienté sur les problèmes. Il doit fournir une réponse dans un contexte précis, il doit être flexible et adaptable et ne cherche pas à démontrer. Par ex :

  • Comment configurer l’environnement de développement ?
  • Comment installer manuellement des extensions ?

3 – Man Pages (page manuel)

Elle sont orientée information et explique la machine interne. Elles sont connectées à la structure projet. Ces pages ne cherchent pas à résoudre les problème mais à expliquer les fondamentaux.

4 – FAQs / Historique

Ces pages apportent la compréhension, le contexte et répond aux questions que l’on se pose. Par ex :

  • Puis-je ouvrir plusieurs comptes ?
  • Quelles sont les versions disponibles ?

 

Organicité des contenus

Le contenus évolue au fur et à mesure du temps. On n’est pas des machines et on a besoin d’une structure.

Publier correctement

Il y a deux objectifs pour publier correctement : il faut que la documentation soit accessible et qu’elle soit contribuable.

Il faut donc publier dans un format textuel et léger, avec un formatage simple et facile à prendre en main.

La chaîne de production doit livrer vers du web, et du pdf (entre autres).

Penser également à versionner les contributions.

Quid de l’automatisation, de l’internationalisation ?