Stratégies pour rédiger une documentation technique efficace

Je fais de la rédaction technique d'une sorte ou d'une autre depuis 1999, lorsque je faisais du contrôle qualité pour la branche R&D d'Altec Lansing à Kfar Saba, en Israël. À l'époque, nous produisions des périphériques audio innovants, comme (halètement) des périphériques audio USB qui fonctionnaient sous Windows ME et 2000. Ils étaient bogués et leur configuration n'était pas aussi simple qu'aujourd'hui.

Nous avions besoin de documents.

Nous avions des obstacles que les utilisateurs devaient franchir, et nous avions besoin d'un moyen de documenter de quoi il s'agissait, quels étaient les cas extrêmes et comment diagnostiquer et résoudre tout cela. Il devait être bien emballé, proprement formaté et accessible aux utilisateurs ayant installé notre application d'assistance. J'ai trouvé l'application Robohelp, utilisée pour créer des applications d'aide standard sous Windows, et j'ai ajouté un fichier d'aide à notre installation.

Au cours de notre processus d'assurance qualité, nous identifiions les problèmes, documentions ce que nous pensions être important et l'organisions dans le fichier d'aide fourni avec l'appareil. J’avais 19 ans à l’époque, je n’avais aucune expérience dans ce domaine et c’était un processus extrêmement naïf. Néanmoins, cela semblait être la bonne chose à faire pour nos utilisateurs, et mon responsable ne m'a pas explicitement dit de ne pas le faire.

Cela fait 24 ans et depuis, j'ai documenté de nombreux projets. L'ampleur a augmenté et la façon dont je considère ces types de projets a considérablement changé.

J'ai quelques réflexions sur ce qui fait de bons documents et j'aimerais les partager avec vous si vous êtes intéressé.

Concept de documentation de base

J'aimerais commencer par un ensemble de règles plus concrètes qui, à mon avis, sont essentielles au succès d'un produit de documentation.

• Les documents doivent utiliser de petits mots pour décrire de grandes idées . N'utilisez donc pas de mots fantaisistes ou de phrases complexes pour décrire ce qui peut être dit en termes plus simples. Vous perdrez des utilisateurs en cours de route et cela ne vaut pas l'ego de votre écrivain.

• Les documents doivent raconter une histoire lorsque vous le pouvez , car un ensemble de tâches personnelles et pertinentes qui racontent une histoire sera plus engageant et mémorable pour votre utilisateur qu'un ensemble abstrait d'instructions.

• Les documents devraient être consultables - parce que sérieusement : c'est une évidence. Si vos documents ne sont pas faciles à trouver, vos utilisateurs ne trouveront pas ce dont ils ont besoin.

• Les documents font presque toujours partie d’une stratégie plus large – et cela est particulièrement vrai lorsqu’il s’agit de produits logiciels. Cela touche au sujet plus large de la défense des intérêts des développeurs, mais en bref : vos documents doivent être soutenus par des didacticiels vidéo, des exemples d'utilisation réels et une assistance technique en direct.

• Les documents doivent être testés - car vous pouvez être sûr que tout va bien, mais sans vrais utilisateurs, comme avec tout autre produit, vous ne le saurez pas avec certitude. Testez-le et testez-le à nouveau.

  
  

Les documents holistiques sont des produits bien conçus

Lorsque vous apprenez un nouveau langage de programmation , les concepts et les idées de ce langage se retrouvent dans votre sac d'astuces pour résoudre des problèmes. Cela fait de vous un meilleur développeur de logiciels et, en fin de compte, vous créez de meilleurs logiciels parce que vous êtes plus conscient et plus compétent.

Ma carrière a été compliquée et a inclus beaucoup de conception de produits logiciels, de développement de logiciels, de support technique et de plaidoyer pour les développeurs. Chaque discipline a influencé ma façon de penser et d’aborder les autres.

Lorsque j'aborde un projet de rédaction technique, c'est avec cette vision large de ce dont un utilisateur va avoir besoin. Je pense que c'est la bonne façon de penser les documents : de manière holistique. Les documents ne sont pas une chose bien définie et pour en créer de bons, vous devez être flexible.

Pour moi, cela signifie que vous devez penser à vos utilisateurs sous autant d’angles que possible. Vous ne pouvez rien prendre pour acquis ou vous allez laisser tomber un groupe d'utilisateurs d'une manière qui aura un impact négatif sur votre marque, votre produit ou votre entreprise d'une manière dont il sera difficile de revenir.

Vos documents constituent très souvent une expérience décisive pour vos utilisateurs.

Si vous faites du bon travail, vos utilisateurs utiliseront votre produit avec succès et deviendront les champions de votre marque. Si vous ne le faites pas, ils n’utiliseront probablement plus jamais votre produit car vos documents leur ont laissé un mauvais goût. Ils le feront également savoir aux autres. Un bon marketing commence ici, alors gardez cela à l’esprit.

Faire de bons documents

Créer de bons documents signifie simplement que vous devez aborder la création de vos documents comme vous le feriez pour tout autre processus de produit.

Vous devez:

• Sachez pourquoi vous créez vos documents
• Sachez qui est votre public cible
• Sachez quels sont leurs points faibles
• Améliorez vos documents au fil du temps

Examinons chacun d'eux de plus près.

Connaître le pourquoi de vos documents est souvent une question et une réponse très simples posées à la surface. Vous créez des documents parce que si vous ne le faites pas, les utilisateurs passeront entre les mailles du filet et ne parviendront pas à utiliser votre produit. À un niveau plus profond, il existe une réponse spécifique à votre cas d'utilisation. Vous disposez d'un outil de développement ? C'est un ensemble de réponses. Vous disposez d'un outil de conception de vente au détail ? Vous disposez d'un produit de comptabilité SaaS ? Vous possédez une cafetière automatique ? Ce sont tous des ensembles de réponses distincts.

La forme de vos documents est décrite par celui qui l'utilisera. Est-ce en ligne ? Est-ce fourni avec une application ? Est-ce imprimé ? Chaque base d'utilisateurs aura besoin de quelque chose d'autre et vous devez être clair dès le départ qui il s'agit.

Votre travail consiste à comprendre ce qui est difficile pour chacun de vos utilisateurs et à créer vos documents en les canalisant vers un contenu informatif qui résout leur problème spécifique.

Plus important encore, vous devez savoir que vous n’y arriverez probablement pas du premier coup. Cela signifie que vos documents doivent être maintenus et mis à jour à mesure que vos produits se développent et évoluent au fil du temps. Espérons que cela se fasse dans un cadre permettant une communication facile avec les utilisateurs que vous essayez d'aider. Vous devez parler à vos utilisateurs, écouter leurs besoins et essayer d'utiliser vos documents pour améliorer leur expérience d'utilisation de votre produit.

Vos documents font partie intégrante de votre réussite

Je résumerai en soulignant simplement à quel point les documents sont d'une importance cruciale. Sans eux, vos utilisateurs sont livrés à eux-mêmes et doivent se débrouiller seuls.

Cela signifiera toujours moins de cas de réussite, une moins bonne visibilité de votre produit au sein de votre écosystème, davantage de développeurs ou d'utilisateurs mécontents et un impact négatif sur votre marque ou votre entreprise.

Les documents sont un sous-produit sérieux à part entière, constituent un investissement et doivent faire partie de votre stratégie produit plus large.