Pourquoi la documentation des produits technologiques est-elle si difficile à utiliser ? (du point de vue de l'utilisateur)

De nos jours, notre documentation sur les outils de développement est difficile à utiliser et nous avons tendance à trouver la solution sur d'autres sources telles que Youtube, les problèmes de GitHub ou les articles de blog. Son contenu peut facilement prendre du retard ou le point clé n'a pas du tout été mentionné. Je considère ce problème comme un problème émergent que nous devrions régler dès que possible, et je pense que deux problèmes majeurs devaient d'abord être résolus. (Du point de vue de l'utilisateur)

• La documentation est trop difficile à contribuer
  • La documentation devient facilement obsolète. Les gens ont tendance à écrire un article de blog plutôt que de contribuer à un document car cela demande beaucoup d'efforts supplémentaires sans les incitations correspondantes.
• Le contexte est groupé

  • La documentation elle-même se connecte à peine à d'autres ressources. Le contexte qui fait une bonne documentation est groupé.

    
    

Dans cet article, je voudrais présenter deux concepts autour de la documentation qui, à mon avis, sont problématiques, puis l'étendre davantage à 3 points de réflexion pour résoudre ces deux problèmes.

Tout d'abord, rappelez-vous de la documentation que vous avez visitée récemment et rejoignez-moi avec l'explication ci-dessous. Je voudrais prendre Next.js par exemple qui est actuellement ma documentation la plus visitée. Commençons par la page "Getting Started".

https://nextjs.org/docs/getting-started

La documentation de Nextjs a une structure qui est populaire à travers divers produits, permettez-moi d'appeler cette structure "Structure de liste isolée". La raison pour laquelle je les appelle isolés est qu'ils sont principalement maintenus par les personnes derrière Next.js (bien qu'ils soient open source).

De plus, je voudrais conclure l'état d'esprit derrière cette documentation en tant que "point à puce du propriétaire".

Puce du propriétaire

La raison pour laquelle je l'appelle "le point central du propriétaire" est que le processus de génération de la documentation est généralement effectué par le propriétaire du produit. Au démarrage d'un produit, personne ne comprend mieux que le propriétaire. Les propriétaires sont la meilleure personne pour maintenir une documentation appropriée pour leurs consommateurs et leurs responsables.

Mais après un certain temps, le produit reçoit beaucoup d'amour et commence à construire la communauté. Il devient de plus en plus difficile de suivre les cas de coin et les bogues. Les propriétaires doivent rattraper les nouveaux engagements et résoudre les problèmes quotidiennement, d'autre part, ils doivent expliquer les nouvelles conceptions, les mises en garde et fournir des informations aux nouveaux arrivants pour surmonter ces problèmes. La charge augmente considérablement.

Tous les produits ne peuvent pas rattraper leur retard, le contenu commence à prendre du retard et certaines solutions peuvent exister dans les articles de blog des autres, les réponses de StackOverflow, les problèmes de GitHub ou les discussions. Un utilisateur a besoin de connecter ces solutions avec des moteurs de recherche, parfois la solution sur la documentation est même fausse.

Structure de liste isolée

La structure de liste isolée est très courante, dans le commerce électronique, dans les sites Web à usage général, sur votre téléphone et dans la documentation. Il y en a partout.

La structure est principalement arbitraire et opiniâtre venant de l'état d'esprit du "point à puce du propriétaire", car le propriétaire doit d'abord proposer l'arborescence de la structure, dans un ordre qu'il pense être le plus approprié pour son client.

La structure des listes isolées est une épée à double tranchant : pour être clair, je ne suis pas totalement contre cette structure, elle est vraiment utile dans un contexte général. Par exemple, c'est bon pour l'exploration initiale et si vous connaissez le document, il vous est assez facile de trouver les informations que vous souhaitez.

Mais d'un autre côté, c'est une structure figée, il est difficile pour la structure d'évoluer et à chaque fois que le mainteneur veut ajouter quelque chose d'autre, il est difficile de trouver un endroit approprié si le propriétaire n'y a pas bien pensé dès le départ. De plus, les utilisateurs n'ont d'autre choix que d'explorer votre documentation. Ils n'ont qu'un seul itinéraire et ce n'est pas suffisant.

Imaginez une structure dynamique, comme un graphique dirigé par la force (quelque chose comme Obsidian peut accomplir ou un diagramme en arbre, vous pouvez trouver de nombreux exemples directement dans leur section de publication[^1]). Je ne dis pas que les graphiques dirigés par la force ou les diagrammes en arbre sont meilleurs que les structures de liste isolées. Ce que je veux, c'est encourager chacun à ne pas penser de manière "listing" mais de manière plus "dynamique", afin que les gens puissent choisir ce qui correspond le mieux à leurs besoins. Ils peuvent utiliser des diagrammes en arbre pour explorer la structure et utiliser le graphique dirigé par la force pour reconnaître le lien entre les sujets. Ou nous pourrions proposer une nouvelle structure à partir de zéro qui peut résoudre certains de ces problèmes.

En combinaison, l'état d'esprit et la structure conduisent au problème que je pense être problématique, répertorié ci-dessous.

La documentation est trop difficile à contribuer

En combinaison avec l'état d'esprit arbitraire du "point de balle du propriétaire" et de la "structure de liste isolée", ce que nous avons, c'est que la documentation actuelle ne peut être correctement maintenue que par le propriétaire, il n'y a pas d'autre moyen facile de contribuer à la documentation. Le problème est double.

Tout d'abord, sur la base de l'état d'esprit "Propriétaire", l'auteur ne veut pas qu'une personne inexpérimentée gâche votre documentation et il est assez difficile de faire correspondre le ton de la documentation si vous ne passez pas beaucoup de temps à rester aligné avec vos mainteneurs.

Deuxièmement, votre utilisateur n'a aucune incitation à contribuer à la documentation, les gens aiment votre produit mais s'ils n'obtiennent aucun crédit dans la construction du document ou une certaine propriété envers une page de documentation, il n'y a aucune incitation.

Vous pouvez prétendre qu'ils peuvent publier un problème et expliquer leur suggestion, mais le problème demeure. Le sentiment de contribuer est très simultané, c'est comme le sentiment d'acheter quelque chose. Imaginez un monde parallèle, ici, si vous voulez acheter quelque chose, vous devez écrire 200 mots pour décrire pourquoi vous voulez acheter ce truc et quel en est l'avantage pour la communauté.

Il n'est pas nécessaire d'empêcher les gens de contribuer à la documentation avec la bureaucratie. Nous devons trouver une autre structure qui puisse rester l'autorité de la documentation et bénéficier en même temps de la contribution simultanée.

Le contexte est groupé

Le matériel d'une bonne documentation n'est pas seulement la documentation elle-même, mais les discussions, les problèmes, les articles de blog et les vidéos correspondants. J'appellerai ces matériaux "Contextes".

Jusqu'à récemment, nous avions tendance à stocker ces contextes de manière distribuée. Un projet open source régulier stocke sa discussion dans une discussion GitHub ou un forum de discussion, ses cas d'utilisation dans des sites Web de produits, des problèmes directement dans les problèmes GitHub et un site Web de documentation auto-hébergé ailleurs. En plus de cela, il existe de nombreux contenus générés par la communauté sur YouTube et des articles de blog personnels.

En réalité, le contexte d'un produit devient clusterisé. Ils n'auront pas d'interconnexion les uns avec les autres. Il peut y avoir une discussion sur la solution au bogue spécifique, mais il n'y a pas de lien inverse dans la section de documentation qui a mentionné cette solution. Malheureusement, nous devons faire face à la réalité que le lien bidirectionnel n'est pas ce dont l'Internet actuel est capable.

Le contexte groupé est volatil

Imaginez une situation où vous déposez la documentation du produit et découvrez rapidement que la documentation ne fournit pas de solution, plus tard le jour où vous trouvez une solution viable sur le blog de quelqu'un d'autre.

Pour le moment, avec la documentation actuelle, il n'y a pas d'autre moyen de rappeler aux autres développeurs qu'ils peuvent résoudre le même problème avec cette méthode décrite par le billet de blog, vous ne pouvez pas ajouter de référence à la documentation. Ce que vous pouvez faire, c'est ouvrir un problème (si c'est open-source) ou ouvrir une discussion sur un forum pour rappeler aux gens cette solution qui sera bientôt inondée par d'autres contenus.

Chaque solution utile dans n'importe quel contexte doit être résistante au flot d'informations dont nous disposons actuellement. Ils doivent rejoindre ce champ de bataille sans point d'ancrage en dehors des moteurs de recherche.

La liste géniale [^2] est une bonne idée, elle fournit un moyen de conserver un bon contenu, mais elle a le même problème avec la "Structure de liste isolée" et l'état d'esprit "Propriétaire".

Si la situation reste telle quelle…

La conséquence immédiate de ces problèmes sera que la « Documentation » sera réputée se dégrader avec le temps. Vous pouvez consulter la documentation de certains géants de la technologie, notamment la documentation sur les services Web d'Amazon ou la documentation sur le cloud de Google, elles sont toutes écrasantes et difficiles à lire.

Le pire sentiment est que vous êtes bloqué sur un problème spécifique que vous ne trouvez pas dans la documentation et nulle part ailleurs. Nous serons davantage confrontés à ce genre de situations si la structure de notre documentation ne peut pas s'aligner sur la portée du produit que nous utilisons.

Il peut sembler écrasant de proposer un nouveau type de structure pour surmonter ces problèmes en premier lieu. Mais en y regardant de plus près, on pourrait séparer l'ensemble des problèmes en 3 questions à se poser.

• Comment inciter les utilisateurs à contribuer à la documentation et à ne pas interférer avec l'objectif général du document ? Pouvons-nous avoir une expérience plus interactive pour la documentation ? Un utilisateur peut-il contribuer directement à la documentation sans quitter la page ?

• Comment rassembler le contexte pour une meilleure expérience de recherche qui ne repose pas sur des solutions de recherche extérieures et qui apporte l'inter-connectivité de chaque contexte en cours de route ?

• Comment expérimenter une nouvelle structure qui peut bénéficier à l'expérience utilisateur et l'itérer dans le temps, voire laisser les utilisateurs la choisir librement ?

  
  

https://twitter.com/EiffelFly

[^1] : page de publication d'obsidienne [^2] : sindresorhus/awesome