Idée de fonctionnalité qui permet de suivre ce que j'ai lu et pas lu dans une documentation

[stephane-klein]

En lisant ce Thread Reddit What do you do with an engineer that won't read the documentation?, je repense à une idée de fonctionnalité de documentation. Je souhaite la décrire dans cette issue.

Une organisation humaine qui est "Documentation centric", qui essaie de suivre une méthode stigmergie, produit beaucoup de documentation, qui peuvent être plus ou moins mise à jour fréquemment.

Par exemple :

• j'aime beaucoup Le guide de la communauté beta.gouv
• le très réputé Handbook de GitLab (avec ses milliers de pages 🙈)
• ...

Constats :

• en phase d'onboarding, la taille de cette base documentaire peut être déroutante. La personne qui arrive dans une organisation, reçoit énormément "d'input" pendant ses premiers jours.
  
  Si cette personne suis linéairement la documentation, beaucoup d'information ne vont pas lui sembler pertinentes, ce qui est normal, parce qu'au moment de la lecture, il lui manque d'autres connaissances (des dépendances), le contexte.
  
  Conséquence : la personne "zappe" ces informations, des petits paragraphes, qui lui seront utiles par la suite, peut être dans deux semaines, dans un mois…
• après une plus longue durée dans l'organisation, il peut être difficile pour une personne de suivre ce qui a changé, dans les documentations de process. La personne ne sait pas ce qu'elle a lu ou pas lu.
• il est très difficile de savoir quel est le niveau de lecture d'une doc, quel est par exemple le niveau de diffusion d'un paragraphe, est-ce que seulement 5% des personnes l'ont lu ? ou 80% ? Cette information peut être utile quand un collègue a besoin de l'aide. Par exemple, ça ne sert à rien de lui demander de relire la documentation si elle l'a déjà lu… peut-être que la documentation n'est pas compréhensible. Inversement, si la documentation n'a pas été lu, peut-être qu'elle est difficile à trouver.

Pratique que j'aime suivre :

• j'apprends beaucoup de chose en lisant les commentaires sur HackerNews, Reddit, LinuxFR…

  • Sur https://linuxfr.org, j'aime beaucoup la fonctionnalité qui m'indique le nombre et la liste des nouveaux commentaires depuis ma dernière visite
  • Pour HackNews, j'utilise l'extension https://github.com/etcet/HNES/ qui me permet de « Show and highlight new comments since you last view a thread »
  • Pour Reddit, j'utilise https://redditenhancementsuite.com/features/ qui me permet aussi de lister les nouveaux commentaires depuis ma dernière visite

• Quand je travaille dans GitLab, Mattermost, Slack…, j'aime mettre un ✅ sur les messages que j'ai lu :

  • pour identifier rapidement ce que j'ai lu ou pas lu
  • pour informer mes collègues que j'ai bien pris connaissance (ou non) de leur message

Pratique non optimal :

• depuis 20 ans, je relis régulièrement la documentation de PostgreSQL, il m'arrive souvent de découvrir de nouvelles choses lors d'une nouvelle lecture. Problème : je ne sais pas ce que j'ai lu ou pas lu.

Idée de fonctionnalité

J'aimerais pouvoir ajouter la fonctionnalité suivante à des documentations (propulsé par exemple par un des outils listés dans #17) :

• pouvoir annoter au niveau de chaque paragraphe ou plus grande section (à déterminer) :
  • "j'ai lu"
  • "j'ai pas bien compris"
  • "todo à lire"
• je veux pouvoir voir sur chaque paragraphe ou plus grande section :
  • ce que j'ai lu
  • qui parmi les utilisateurs, qui a déclaré avoir lu ce paragraphe
• je veux pouvoir voir facilement tous les paragraphes qui ont été changés depuis ma dernière lecture

Idée d'implémentation :

• peut-être implémenter cela dans une extension browser + un petit serveur pour centraliser l'information
• peut-être sous forme d'une lib JS, à intégrer dans le logiciel de génération de documentation

Comment identifier ce qui a été lu / pas lu ?

• peut-être générer une "empreinte" (sha-1) ou autre du contenu du paragraphe + son url + sa position dans l'arborescience des sections 🤔
• peut-être que le générateur de documentation doit générer un uuid sur toutes les sections pour l'identifier 🤔