Une approche centrée sur les décisions plutôt que sur les tâches

• Se concentrer sur les décisions

  • Une citation de Every Page Is Page One a provoqué un changement majeur dans l’approche de la rédaction de documentation technique
  • Dans la communication technique, on parle surtout d’aide à l’exécution des tâches, mais dans bien des cas, les informations dont les gens ont besoin pour accomplir une tâche ne concernent pas le fonctionnement de la machine, mais l’aide à la prise de décision
  • Le simple fait de documenter les procédures ne suffit pas
  • Il faut indiquer quelles décisions l’utilisateur doit prendre et quelles en seront les conséquences, puis l’orienter autant que possible vers des ressources et références qui l’aident à décider

Résumé de GN⁺

• Cet article souligne l’importance de l’aide à la prise de décision dans la rédaction de documentation technique
• Il est nécessaire d’aller au-delà de la simple description des procédures pour aider les utilisateurs à prendre de meilleures décisions
• Pour les rédacteurs techniques, il est important de fournir aux utilisateurs le contexte et les informations dont ils ont besoin
• Parmi les projets du secteur aux fonctionnalités similaires, Confluence et Notion sont recommandés

[GN⁺]

Commentaires Hacker News

• J’écris sur la bureaucratie allemande, et je suis entièrement d’accord avec cette approche
  La plupart de mes guides commencent par « ce que c’est, qui doit le faire et pourquoi il faut le faire ». Si on ne s’assure pas que les gens font la bonne chose pour les bonnes raisons, ils peuvent partir très loin dans la mauvaise direction
  La plupart des sites web gouvernementaux n’expliquent pas cela et demandent seulement ce qu’il faut pour terminer la procédure dont ils ont la charge. Ils ne la considèrent pas comme une partie d’une décision plus large et partent du principe que l’utilisateur sait déjà ce qu’il vient faire

  • À propos du dernier paragraphe, le site du gouvernement britannique fait cela très bien. Il y a une page d’accueil qui explique la procédure, avec des avertissements et points d’attention, et ce n’est qu’ensuite qu’on peut remplir le vrai formulaire
    Si vous cliquez sur « Start Now » dans le résultat Google pour le renouvellement du permis de conduire, https://www.gov.uk/renew-driving-licence, vous verrez ce que je veux dire
    Du point de vue d’un « power user », cela peut parfois sembler gênant, mais je comprends qu’il faut penser à tout le monde
  • Ce commentaire me fait penser que vous aimeriez Every Page Is Page One. L’idée centrale est que les gens peuvent arriver sur n’importe quelle page d’un site de documentation, donc chaque page doit donner rapidement le contexte et permettre à l’utilisateur de juger facilement s’il est sur la bonne voie
    C’est aussi de là que vient le titre du livre. Pour l’utilisateur, n’importe quelle page du site peut être sa première page
  • J’aimerais que davantage de documentation technique adopte cette approche. J’ai tendance à toujours me demander pourquoi on fait les choses d’une certaine manière, donc je pars souvent sur des pistes annexes et cela me ralentit

• Cela s’accorde très bien avec la manière d’utiliser les LLM. Je demande toujours d’abord des options, puis je décide moi-même laquelle a le plus de sens
  En substance, je les utilise comme une sorte de document magique et étrange, qui produit à chaque instant de la prise de décision des options possibles, imparfaites mais utiles

  • Pensez aux apprentis qui travaillaient sous de grands artistes comme Léonard. Le maître trace les contours et les esquisses, puis les élèves remplissent les blancs sous sa supervision. Parfois, le maître vole aussi les idées de ses élèves
  • Pourrais-tu donner un exemple de cette manière de faire ?

• C’est vraiment bien. C’est court, va droit au but et c’est perspicace. J’ai plutôt une façon de penser orientée vue d’ensemble, donc il est important pour moi de comprendre non seulement comment faire quelque chose, mais aussi pourquoi, et comment cela s’inscrit dans un contexte plus large
  J’encourage les développeurs à utiliser activement le champ Description des stories et tâches Jira, pour y mettre un aperçu de pourquoi nous faisons ce travail et de la manière dont il s’inscrit dans le tableau d’ensemble
  Certains semblent détester ça, mais d’autres aiment beaucoup
  Moi, je suis content de fournir la vue d’ensemble, et les développeurs sont satisfaits de pouvoir travailler de manière plus autonome en la comprenant

• Mesurer si la documentation aide les gens à prendre de bonnes décisions semble bien plus difficile que de mesurer si elle les aide à accomplir correctement une tâche
  Si l’on optimise pour une documentation orientée tâches et procédures, c’est parce que l’entreprise demande à l’équipe documentation de prouver sa valeur, qu’il existe une demande pour ce type de documentation, et qu’il y a beaucoup de moyens de la mesurer et d’en rendre compte sur une courte période
  Mais une question comme « cet ensemble de documents a-t-il aidé quelqu’un à construire la bonne chose de la bonne manière ? » est déjà difficile pour une organisation quand il s’agit de son propre produit ; si on l’abstrait à l’efficacité de la documentation, cela devient très flou
  Cela ne veut pas dire qu’on ne peut pas écrire une documentation qui aide à décider, mais qu’il est très difficile de prouver par des chiffres qu’on l’a fait. On peut classer différents ensembles de documents selon leur capacité à aider des utilisateurs qui doivent prendre des décisions, et expliquer pourquoi, mais je ne sais pas vraiment comment quantifier cela de la manière attendue par une entreprise
  Je me demande aussi en quoi la structure d’un ensemble de documents conçu pour soutenir la prise de décision différerait de celle d’une documentation conçue pour soutenir l’exécution de tâches. Les grandes catégories resteraient sans doute les mêmes — concepts, référence, guides — mais il y aurait probablement bien plus de documents conceptuels, et davantage d’espace pour contextualiser ces concepts. Je m’attendrais aussi à plus de dépendances entre sujets et de renvois croisés

  • Il est intéressant que ta première pensée ne soit pas « comment utiliser cela pour améliorer la documentation que j’écris », mais « comment prouver que cela améliore la documentation que j’écris ». On dirait que tu travailles dans un environnement assez contraint
  • Dans un endroit où l’on peut librement faire ce qu’on pense être le mieux pour les utilisateurs, comme sur un projet personnel, je prendrais probablement le soutien à la décision comme base de la stratégie documentaire
    Par conscience professionnelle, si j’ai le sentiment que le « soutien à la décision » est ce qu’il y a de mieux pour mon projet, j’aurais l’impression d’avoir le devoir d’apporter aussi cette stratégie à la documentation de travail
    Heureusement, je n’ai pas de managers myopes qui me serrent la gorge, mais si je devais convaincre au travail, je procéderais ainsi. D’abord, j’expliquerais la logique de la stratégie. Le soutien à la décision se tient et c’est convaincant. On continuerait à produire de la documentation orientée tâches, mais les tâches ne sont qu’un sous-ensemble du soutien à la décision
    Ensuite, je présenterais en détail des exemples tirés des tickets de support, des discussions de chat, etc., où le manque de soutien à la décision posait problème. Par honnêteté intellectuelle, je montrerais la liste complète des tickets de support liés à la documentation, ainsi que le sous-ensemble concernant le soutien à la décision. Si la part est loin d’être négligeable, par exemple 25 %, alors il faut examiner plus en profondeur le « soutien à la décision »
    Enfin, les parties prenantes pourraient citer des exemples vécus dans leur propre travail. Du genre : « Vous vous souvenez à quel point il était difficile de décider par quoi remplacer le CMS ? »

• En général, c’est ce que j’appelle une approche heuristique
  J’ai l’impression que le travail demande une approche proche de la logique floue. Cela dit, ça fonctionne mieux quand l’ingénieur a déjà un certain niveau d’expérience
  S’il manque d’expérience, même s’il est compétent et intelligent, il faut être beaucoup plus directif

  • Thinking in Bets a été l’un des livres les plus utiles pour ma manière d’aborder l’ingénierie logicielle. Ce n’est pas un livre sur le code, mais sur la manière de prendre efficacement des décisions dans un contexte d’information limitée
  • Je ne suis pas sûr de comprendre ce que signifie aborder le travail selon une logique floue. Pourrais-tu développer un peu ?

• Dans un contexte d’équipe, une bonne approche de la prise de décision est expliquée ici par Rich Hickey : https://www.youtube.com/watch?v=c5QF2HjHLSE
  La conférence s’intitule « Design in Practice », mais en réalité elle porte sur la prise de décision

• « Le travail, c’est simplement tout ce qu’il faut faire pour passer d’une décision à la suivante. » — Venkatesh Rao, Tempo

• J’ai défendu quelque chose de similaire. Il ne faut pas décrire les outils seulement à un niveau élevé — surtout que les gens passent souvent en mode marketing — mais expliquer quel problème l’outil a été conçu pour résoudre et quels compromis ont été faits au passage
  Cela rend beaucoup plus facile de replacer l’outil, ainsi que les choix et modes disponibles, dans leur contexte, et de juger rapidement s’il nous convient

• Ce conseil me semble un peu confus. De quelles décisions parle-t-on ? De celles du créateur de l’outil, ou de celles de l’utilisateur ?
  En général, cela ressemble à une simplification excessive. Il est plus utile de commencer par comprendre si la documentation qu’on consulte relève de l’apprentissage, de l’orientation vers un objectif, de la compréhension ou de l’information [1]
  Par exemple, si je cherche l’API d’une fonction, recevoir un déluge d’informations sur les « décisions » peut être agaçant
  1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

  • La documentation doit toujours traiter des besoins des utilisateurs. Cela ne disparaît pas. Il en va de même pour Diátaxis, les quatre quadrants de la documentation mentionnés plus haut
    Si cet article trouve un écho, c’est à mon avis parce qu’il met en lumière un angle mort de deux stratégies bien connues. Tout le monde essaie de produire une documentation centrée sur l’utilisateur, et beaucoup d’équipes suivent Diátaxis, mais on a toujours du mal à aller jusqu’au bout des tâches à l’aide de la documentation
    Partir du principe fondamental que « la documentation doit soutenir les décisions » peut être une voie pour la rendre plus utile

• Il est important de savoir comment les gens utilisent mon système pour prendre des décisions. Je considère qu’une telle connaissance est essentielle pour maintenir, étendre ou reconstruire le système
  Mais l’article propose une responsabilité plus élevée. Il dit qu’il faut documenter le processus de décision de l’utilisateur, et exposer le contexte, les options et les conséquences de la décision
  J’ai travaillé sur un « système d’aide à la décision » avec ce type de responsabilité, et c’est devenu extrêmement complexe très vite. Les gens aiment contester les résultats même quand ceux-ci sont annoncés comme certains à 100 %. Ils n’aiment pas non plus les e-mails automatiques qui intègrent de l’incertitude, et dans la réalité ils n’aiment pas davantage qu’une documentation exige un choix binaire alors qu’il existe beaucoup plus d’options
  Au-delà de cet article, j’aimerais que le livre traite de la notion de contrôle. Pour documenter un comportement, il faut un certain degré de garantie ou de contrainte sur ce comportement pour que la documentation conserve son autorité. Personnellement, je pense que l’absence d’autorité et de contrôle est un angle mort fréquent et important d’initiatives de rédaction comme https://www.plainlanguage.gov

  • Pour citer à nouveau ce que j’avais écrit sur r/technicalwriting à propos de cet article, le point vraiment important dans l’idée de Baker est que le dogme de l’enseignement de la rédaction technique est absolument centré sur les tâches
    Si l’on interroge des rédacteurs techniques professionnels, la majorité dira probablement qu’« aider les utilisateurs à accomplir des tâches » est l’objectif principal de la documentation, voire LE principal objectif
    La courte citation de Baker est assez radicale au sens latin de « retour à la racine », car elle suggère qu’une de nos hypothèses fondamentales est gravement insuffisante
    Personnellement, je trouve l’idée de Baker intéressante parce qu’elle fixe un niveau d’exigence bien plus élevé que celui qu’on attend aujourd’hui de la documentation technique. Beaucoup de documents partent du principe que si une tâche est documentée, alors « mission accomplie », mais Baker semble dire que cela ne suffit pas
    Bien sûr, il faut toujours documenter les tâches, mais les tâches ne sont qu’un sous-ensemble des informations qui composent une décision
    Je ne me souviens pas si le livre de Baker abordait le contrôle dans le sens évoqué ici. Pour moi, c’est une idée nouvelle, donc merci
    Voici un exemple concret de contrôle qui me vient à l’esprit. Une grande partie de ma documentation dépend de pages d’autres projets open source, et si la qualité de ces pages externes est faible, il est probablement aussi de ma responsabilité d’améliorer cette documentation. Beaucoup considèrent que la documentation hors de leur propre site ne relève pas de leur responsabilité, mais si l’on veut vraiment aider à prendre des décisions, peu importe qui héberge cette documentation
    Il y a peut-être beaucoup à apprendre d’une attitude consistant à être un bon citoyen de l’open source