Article original : Why is so much enterprise documentation so awful?
Je passe une très grande partie de ma journée de travail professionnelle à lire de la documentation technique. Peut-être que « lire » n'est pas tout à fait la bonne façon de le décrire. À ce stade, c'est plus comme balayer rapidement les menus, les FAQ et les titres de paragraphes pour trouver des indices sur l'endroit où je peux trouver le morceau exact d'information que je cherche.
Avec quelques exceptions, cela tend à être le cas que je cherche simplement une confirmation rapide de la bonne syntaxe de ligne de commande ou que j'essaie de comprendre une toute nouvelle technologie.
Documentation technique basée sur le Web : l'art de la sous-performance
Maintenant, je n'ai aucune plainte à l'égard des personnes qui fournissent des guides de syntaxe détaillés et des pages principales — pourquoi devraient-elles reformater tout leur document pour mettre en évidence un détail obscur pour lequel je pourrais un jour venir chercher ?
Mais lorsque j'essaie de me familiariser avec un logiciel compliqué — pour comprendre son but et son cas d'utilisation principal — il est raisonnable pour moi de m'attendre à un chemin relativement prévisible et confortable vers mon objectif. Au lieu de cela, je rencontre souvent une page d'accueil de projet avec des liens vers plusieurs cibles avec des noms comme « Bien démarrer », « Comment utiliser… ? », « Documentation » et, profondément enfoui sous quelques couches de menu, « Guide de démarrage rapide ».
Souvent, les pages vers lesquelles je suis envoyé seront incomplètes, apparemment victimes de changements d'avis et de dépassements de budget. D'autres couvriront des versions obsolètes du logiciel qui pourraient facilement avoir un ensemble de fonctionnalités significativement différent de la dernière version. Pire encore : les fonctionnalités peuvent encore exister, mais entre-temps, elles ont changé de noms et même d'icônes.
Même si nous ignorons la qualité de l'écriture — quelque chose qui peut être remarquablement difficile et coûteux à contrôler — et l'intelligibilité des documents individuels, il semble souvent y avoir des problèmes significatifs de contrôle de version et de gestion de projet.
Je peux généralement deviner ce qui s'est passé : certains clients se sont plaints de ne pas savoir comment utiliser le logiciel, donc la direction — incapable d'évaluer correctement l'état actuel de la documentation par elle-même — a ordonné la création d'un nouvel ensemble complet à partir de zéro. Le projet commence, mais à peu près à mi-chemin, le contributeur clé quitte l'entreprise ou est distrait par d'autres échéances et demandes.
Et là, il reste jusqu'à ce que quelques autres clients se plaignent de ne pas savoir non plus comment utiliser le logiciel. Rincer. Répéter.
Une mauvaise documentation est-elle toujours mauvaise ? Absolument pas. Je suis souvent surpris de voir à quel point certains projets open source parviennent à accomplir des choses considérant les ressources limitées avec lesquelles ils travaillent généralement. Et, dans tous les cas, tant que les gens (comme moi) n'offrent pas leur aide, nous n'avons aucun droit de râler.
Toute la documentation est-elle mauvaise ? Non. Bien que vous pourriez soutenir qu'il y en a beaucoup trop, Amazon's AWS maintient une ressource de documentation magnifique qui est bien écrite, bien conçue et si bien organisée à travers le système que trouver des éléments dans n'importe quelle page donnée est prévisible et rapide. AWS n'est pas la seule histoire à succès, mais ce n'est pas non plus exactement une partie d'un champ surpeuplé.
Livres techniques : l'art de la surperformance
À l'autre extrémité du continuum de la documentation se trouvent les livres. Vous vous souvenez de ceux-là ? Bien que je n'aie peut-être pas acheté de livre technique depuis des années, des milliers d'autres personnes le font tout le temps. En fait, au moins à court terme, l'industrie de l'édition technologique semble remarquablement saine.
Les meilleurs éditeurs traditionnels soumettront une proposition de livre à une analyse très approfondie avant de conclure que l'idée a du sens et qu'il y a suffisamment de lecteurs intéressés pour que cela en vaille la peine. Une fois l'écriture commencée, ils enverront des couches et des couches d'éditeurs et de relecteurs à chaque étape de la production d'un livre. Et lorsqu'ils n'ont plus d'éditeurs, ils organiseront une revue du comité éditorial pour s'assurer que ce n'était pas une terrible erreur.
Avec quelques variations, c'est ainsi que les éditeurs de Wiley/Sybex et Manning ont fait leur travail en travaillant sur mes livres. Et c'est aussi assez similaire au processus que je suis en produisant mes cours vidéo avec l'équipe de Pluralsight.
Lorsque c'est fait correctement, le système crée des points de contrôle au niveau du thème, du style, du chapitre et même des paragraphes, en demandant si cet élément est nécessaire, est présenté aussi bien que possible et s'intégrera correctement dans la vision globale. Ces points de contrôle font de grands livres, mais ils tendent à être très coûteux.
Est-ce trop ? Parfois. Le système éditorial multi-niveaux complet va-t-il être abordable pour les projets de documentation basés sur le Web ? Peut-être pas toujours.
Mais créer une documentation de haute qualité, lisible et bien organisée est un besoin commercial significatif pour de nombreuses entreprises, donc ce serait probablement une très bonne idée pour elles de soumettre au moins ce qu'elles ont déjà à un audit approfondi par quelqu'un avec de l'expérience, des connaissances techniques et — surtout — de l'objectivité. Les chances sont, cela conduira à un produit de documentation beaucoup plus utile. Et oui : la documentation est aussi un produit.
David Clinton dépose beaucoup de ses biens sur Bootstrap-IT.com. Vous pourriez être surpris par ce que vous y trouvez…