Dans la high-tech, la documentation technique est trop souvent reléguée au rang d'accessoire. Voici comment en faire un véritable atout produit.
Faire de la documentation technique un véritable atout
Rédacteur technique depuis plus de vingt ans, je reste frappé par l'écart entre le potentiel et la réalité de la documentation technique.
Ces dernières années, je me suis interrogé sur la manière dont la documentation technique, dans la high-tech, peut apporter une réelle valeur au produit au lieu de n'en être qu'un simple appendice.
Après avoir testé l'idée sur quelques produits, les résultats m'ont convaincu de la pertinence de cette approche. Depuis, je cherche à pousser l'expérience plus loin. Aujourd'hui, après six mois passés comme rédacteur technique chez DoiT, je souhaite partager quelques enseignements et nouvelles pistes de réflexion.
L'essentiel d'abord
Les rédacteurs techniques rejoignent presque toujours l'équipe d'engineering ou produit dans un second temps (selon la vision qu'a l'organisation du développement produit). Après tout, à l'heure actuelle, tout le monde est rédacteur ou éditeur. Tant que vous en êtes à chercher vos premiers utilisateurs, les dépôts GitHub, les articles de blog et les discussions sur les forums restent souvent plus rentables pour atteindre votre cible.
Ce n'est qu'une fois ces débuts passés et le produit prêt à passer à l'échelle que l'on songe à faire appel à des rédacteurs techniques. D'expérience, leur première mission consiste à poser les règles du jeu, par le biais de conventions.
Il peut sembler étrange de placer les conventions en tête lorsqu'on parle d'un secteur qui se réclame de l'innovation et de la créativité. Pourtant, les conventions ne sont pas les ennemies de l'innovation ni de la créativité. Les appliquer sur les éléments non critiques réduit la charge cognitive et permet de se concentrer sur les tâches essentielles.
Les conventions en matière de documentation technique prennent diverses formes : un guide de style complet ( Google developer documentation style guide, Microsoft writing style guide) ou un simple jeu de règles ( AWS document conventions).
Inutile d'attendre un guide de style parfait pour vous lancer. Mieux vaut le construire au fil de votre découverte du produit. Autrement dit, profitez de votre période d'onboarding.
Voici les étapes à suivre durant cette phase :
- Poser les fondamentaux lors du nettoyage de base :
- Les titres et en-têtes adoptent-ils la casse de phrase ou la casse de titre ; emploient-ils le gérondif (verbe en -ing) ou la forme de base ?
- Les procédures sont-elles présentées en listes numérotées ou sous forme de récit continu ?
- Existe-t-il une règle stricte sur la virgule de série (un excellent sujet pour lancer un débat entre rédacteurs) ?
- Comment décrit-on les interactions UI : l'utilisateur clique sur, sélectionne ou choisit un bouton ?
- Comment réalise-t-on et présente-t-on les captures d'écran ? Et les annotations ?
- Construire votre guide de style interne en chemin :
- Piochez dans les standards du secteur et adaptez-les à vos besoins.
- Considérez-le comme un document vivant, ouvert à de nouveaux usages et à une terminologie inédite.
Un guide de style interne constitue un pilier de la documentation technique. Il vous aide non seulement à faire grandir votre équipe de rédacteurs, mais il oriente aussi les autres collaborateurs amenés à produire des contenus techniques, qu'il s'agisse d'un brouillon destiné aux rédacteurs techniques ou d'un article de blog.
Vous découvrirez aussi en chemin des sujets de plus grande envergure, par exemple :
- Quel est le degré de personnalisation et de ton conversationnel du style général ?
- Comment utilise-t-on les vidéos ?
- Comment traite-t-on les informations sensibles ?
- Qui sont les parties prenantes ou les contributeurs actifs de la documentation technique ?
Ne soyez pas surpris par vos découvertes.
Concevoir la documentation technique
Les produits technologiques sont complexes. Non seulement ils reposent sur des technologies sophistiquées, mais ils interagissent aussi avec d'autres produits, souvent issus d'autres organisations.
Comment aborder cette complexité dans la rédaction de la documentation technique ?
La réponse classique commence par : Ça dépend. Reste que nous disposons de deux outils puissants : le framework et le modèle conceptuel.
Framework
En documentation technique, un framework peut prendre la forme d'un modèle ou d'une structure conceptuelle facilitant la rédaction de sujets isolés (autrement dit, sans lien avec d'autres sujets).
La plupart des articles de blog et des pages uniques de documentation technique portent sur des sujets isolés ; ils tirent donc profit d'un modèle ou d'un framework bien défini.
Vous vous apprêtez à rédiger un guide d'installation ?
Pensez à une structure en trois parties : prérequis (matériel et logiciel), exécution (les étapes concrètes d'installation) et vérification (contrôler la version, exécuter un exemple hello-world, etc.).
Vous compilez des instructions pour interroger des données ?
Veillez à préciser les permissions requises, à fournir des exemples de requêtes et à détailler les entrées et sorties.
Même sans modèle disponible, un peu de pratique suffit pour bâtir un framework relativement aisément. Avant de rejoindre DoiT, j'ai écrit un article intitulé How to write (and rewrite). L'approche qui y est suggérée porte essentiellement sur la construction d'un framework.
Voici les points clés :
- S'appuyer sur le Minto Pyramid Principle® pour révéler la structure sous-jacente d'un texte complexe
- Créer des hiérarchies visuelles pour aider le lecteur à se repérer dans la complexité
- Concevoir des regroupements pour soutenir le parcours utilisateur
Modèle conceptuel
La complexité des produits technologiques tient en grande partie aux interactions, qu'il s'agisse de celles entre composants d'un même produit ou entre produits évoluant dans un même paysage métier ou technologique et devant fonctionner ensemble pour former une solution complète.
En général, vous n'exposez pas la complexité inhérente au produit. Votre recette secrète peut intéresser vos concurrents, pas forcément vos clients.
En revanche, soyez attentif aux complexités susceptibles de générer des frictions externes. Ce sont elles qui freinent le plus souvent vos clients, et même votre propre équipe support.
Dans son ouvrage de référence The Design of Everyday Things, Donald Norman explique qu'offrir un bon modèle conceptuel est le principe le plus important pour apprivoiser la complexité. J'y souscris pleinement.
Voyons de plus près comment exploiter le modèle conceptuel dans la documentation technique, à travers deux exemples tirés du DoiT Help Center.
Fonctionnalités de type brique de base
À propos de la fonctionnalité Attributions, Matan Bordo, product marketing manager chez DoiT, aime dire qu'il s'agit de l'une des fonctionnalités les plus engageantes de DoiT Cloud Intelligence™ lorsqu'elle est bien utilisée. Si vous en concluez qu'il n'est pas évident d'en tirer pleinement parti, nous vous comprenons.
Attributions est une fonctionnalité de type brique de base. Comme beaucoup d'autres briques, elle apporte peu de valeur seule. Mais une fois son essence saisie, son utilisation devient un vrai plaisir.
Lors d'une mise à jour récente, nous avons remanié la documentation de cette fonctionnalité et placé les scénarios en tête, afin d'aider les utilisateurs à cerner ce qu'elle permet de faire avant de plonger dans les détails de configuration.
Fonctionnalités d'écosystème via plugin
En septembre, nous avons publié un article intitulé Visualize with Grafana Cloud (rédigé par notre CTO et cofondateur Vadim Solovey). Comme vous le savez peut-être, Grafana n'est pas une solution DoiT, mais un service très répandu dans le Cloud Native Landscape.
Comme dans l'exemple précédent, nous avons posé dès l'introduction la raison d'être de l'intégration et précisé en quoi elle peut servir une entreprise opérant dans le cloud.
Au sein du produit comme dans l'écosystème, un bon modèle conceptuel décrit les relations entre les composants en interaction et aide ainsi les utilisateurs à se repérer dans le domaine qu'ils ont choisi.
Quels autres bénéfices ? S'il y a une chose dont on peut être sûr en matière de technologie, c'est que les utilisateurs font preuve de créativité pour résoudre leurs problèmes. Avec un bon modèle conceptuel, ils découvriront de nouveaux cas d'usage pour votre produit ; mieux encore, ils deviendront vos évangélistes spontanés et contribueront à le faire progresser.
Un travail d'équipe
Où en sommes-nous, alors ?
Conventions et frameworks peuvent être traités avec des connaissances génériques en rédaction technique (un bon point de départ pour les nouvelles recrues ou les rédacteurs juniors), tandis que la construction de modèles conceptuels solides à différents niveaux exige une connaissance approfondie du produit.
DoiT est une entreprise technologique fière de son expertise cloud poussée et de sa culture orientée client. L'environnement d'apprentissage y est exceptionnel. Les échanges sur les canaux Slack internes et les contenus partagés sur le wiki interne ou StackOverflow regorgent de connaissances, et chacun a à cœur de partager son savoir, d'aider les autres et de collaborer pour progresser, individuellement comme collectivement.
Intégrés à l'équipe pluridisciplinaire de product management, les rédacteurs techniques sont de véritables partenaires de réflexion pour les product managers et les designers. La capacité à écrire clairement repose sur la capacité à penser clairement, un atout précieux pour faire émerger les hypothèses et modéliser les fonctionnalités produit.
Au moment de définir les ambitions de l'équipe de rédaction technique, nous avons fixé pour vision de faire de la documentation technique un véritable atout du portefeuille produits DoiT. La clé : le travail d'équipe. Une documentation technique de qualité n'est pas l'affaire solitaire des rédacteurs techniques, mais un chantier que l'équipe de rédaction technique de DoiT pilote en lien étroit avec l'ensemble de l'organisation.