Quel style de documentation les chefs de produit doivent-ils utiliser pour communiquer le message approprié ?

*La documentation est l'une des composantes les plus cruciales et les moins appréciées de tout projet open-source, et elle ne doit pas être prise à la légère.

D'une manière générale, la plupart des projets open source ne reçoivent pas l'attention nécessaire simplement parce que leurs auteurs ne sont pas vraiment intéressés, sont incapables ou n'ont pas le temps de créer un environnement de documentation efficace pour la documentation de leur API et de leur produit.

Même si votre application est excellente, si la documentation est inadéquate, les consommateurs ne pourront pas bénéficier de son utilisation.

Toutefois, même s'ils n'ont pas d'autre choix que de l'utiliser pour une raison quelconque, ils ne seront pas en mesure de le faire avec succès ou de la manière dont vous le souhaiteriez.

Comprendre comment produire une excellente documentation demande beaucoup de travail, tout comme l'examen périodique d'autres projets de documentation. Mais croyez-moi sur parole - en tant que personne ayant créé une pléthore de documentation pour Docsie - si vous construisez un code qui sera utilisé par quelqu'un d'autre que vous, et en particulier si ces personnes sont vos clients, votre produit doit être bien documenté, formaté et présenté de manière dynamique.

Quelle est la différence entre les tutoriels, les guides pratiques, les explications et les références ?

De nombreuses personnes croient à tort que ces quatre expressions désignent le même objet. Elles expriment pourtant une variété de significations différentes. Ces différents types de documentations sont tout à fait essentiels et présentent quelques différences essentielles :

Documentation didactique: Ces types de documentation sont des documents basés sur l'information et orientés vers la formation.

Documentation de type guide pratique/guide de l'utilisateur : Les guides de l'utilisateur expliquent comment résoudre des problèmes spécifiques en suivant une série d'étapes afin d'atteindre un objectif précis.

Documentation d'explication : Il s'agit d'une documentation de type article conçue pour aider l'utilisateur/le lecteur à mieux comprendre un produit grâce à diverses explications et à un contexte général.

Documentation sous forme de notes de référence : Cette documentation est conçue pour informer l'utilisateur de la description des différentes mises à jour et utilisations des nouvelles fonctionnalités. Ce type de documentation peut être très "brut" sous la forme d'une documentation destinée aux développeurs, mais elle peut également être traduite en notes de mise à jour plus conviviales qui peuvent être facilement comprises par l'utilisateur final.

Raisons de produire une documentation de haute qualité

Avant de poursuivre, il est essentiel de comprendre pourquoi la rédaction d'une documentation compétente est un besoin très important mais sous-estimé dans la société d'aujourd'hui. La disponibilité d'une documentation complète et bien rédigée est l'un des critères les plus importants pour parvenir à une adoption généralisée, en particulier dans les projets open source où pratiquement chaque action est accessible au public et où de telles activités jouent un rôle crucial dans le succès du projet.

Examinons les principales raisons de rédiger une documentation efficace.

Elle vous permet de créer une meilleure expérience d'accueil pour vos clients.

Lorsque vous fournissez à vos clients une documentation adéquate sur votre produit, vous les aidez à se sentir plus à l'aise avec votre produit et protégés par ses directives spécifiques. Pour ce faire, vous devez prendre les mesures suivantes :

1. Veillez à ce que la documentation de votre produit soit visible et facilement accessible, soit par des liens dans l'application, soit par une plateforme de documentation consultable.

2. Veillez à ce qu'elle soit bien rédigée et qu'elle aide le client à trouver sa réponse rapidement et facilement.

Un conseil : ne rédigez votre documentation qu'une seule fois, et elle sera digérée encore et encore lorsque de nouveaux clients seront recrutés par votre entreprise.

En conséquence, il y a moins de demandes d'assistance.

Les clients qui lisent et comprennent votre documentation sont plus susceptibles d'acheter vos produits. Lorsque les clients ne parviennent pas à comprendre quoi que ce soit, cela peut être très agaçant et ils peuvent commencer à blâmer votre produit à la place.

Mais si la documentation est attrayante, facilement accessible et intelligible, ils seront en mesure de résoudre eux-mêmes leurs problèmes sans avoir besoin de vous consulter, ce qui les rendra plus autonomes.

Elle vous aide à soutenir votre propre équipe.

Une base de connaissances solide peut également être utilisée pour aider les membres de votre propre équipe. Ainsi, votre équipe interne devrait être informée des nouvelles fonctionnalités, des feuilles de route prévues, de la documentation de l'API et de tout ce qui est nécessaire pour que tout le monde soit sur la même longueur d'onde.

Instructions étape par étape sur la manière de rédiger une documentation efficace

La rédaction de la substance du document et l'organisation de cette activité sont deux tâches totalement distinctes de la détermination du ton à utiliser et de la manière de s'assurer que votre documentation est compréhensible. Comme l'indique [O'Reilly, il existe 8 règles pour une excellente documentation] (https://www.oreilly.com/content/the-eight-rules-of-good-documentation/) :

1. Créer une documentation qui invite le lecteur.

2. Produire une documentation complète qui couvre tous les domaines du projet.

3. Produire des documents faciles à comprendre.

4. **Créer une documentation qui démontre comment utiliser le produit par le biais d'études de cas.

5. **Rédiger une documentation qui contient des répétitions là où c'est nécessaire.

6. Rédiger une documentation à jour

7. Écrire une documentation à laquelle il est facile de contribuer

8. Écrire une documentation simple à découvrir et à comprendre

Ces éléments concernent principalement le contenu. Ensuite, nous aborderons le "comment" de la structuration de ces informations en six étapes :

Prendre une décision sur ce que vous devez enregistrer.

Prenez le temps de réfléchir au type de documentation que vous allez produire avant de commencer : s'agit-il d'un tutoriel, d'un document de référence, d'un manuel d'instructions ou d'une explication ?

Notez que la nature de votre produit aura un impact direct sur le type de documentation que vous serez chargé de créer.

Créer un cadre.

Commencez par jeter les bases de votre documentation. Il peut s'agir de quelque chose de très petit au début, et cela peut comprendre seulement quelques groupes, mais avec le temps, l'ensemble de la plate-forme sur laquelle vous construisez commencera à croître en taille et en complexité. Vous devez revoir régulièrement votre structure organisationnelle.

Gardez à l'esprit que vous êtes l'instructeur et que vous êtes responsable en dernier ressort de la manière dont vos élèves apprennent dans votre classe. Ils seront guidés par vos instructions ; par conséquent, plus vous consacrerez de temps à la structure, plus vos élèves réussiront dans leurs efforts.

Tirez toujours parti de techniques multimédias solides.

Veillez à utiliser des vidéos, des dessins et des styles variés et à les intégrer directement dans votre documentation. [Docsie ] (https://www.docsie.io/) permet d'intégrer ces éléments dans notre plateforme pour faciliter ce processus.

Non seulement ils aideront les consommateurs à mieux comprendre les informations que vous exprimez, mais ils offriront également une excellente optimisation pour les moteurs de recherche, ce qui se traduira par un plus grand nombre de prospects de haute qualité grâce à votre documentation dynamique.

Veillez à ce qu'il soit possible d'y effectuer des recherches.

Les capacités de recherche varient d'une plateforme de base de connaissances à l'autre : certaines n'offrent qu'une recherche de base sans possibilité d'approfondir les segmentations (ce qui est techniquement correct si vous n'avez pas des milliers de fichiers), tandis que d'autres proposent des options de recherche qui vous permettent de rechercher non seulement dans les documents, mais aussi dans les noms d'utilisateur.

Toutefois, une chose est essentielle : vous devez utiliser un outil qui vous permet d'effectuer des recherches rapides. Une fonction de recherche incluse dans l'application permet de rechercher facilement des fichiers et d'en obtenir un aperçu sans quitter l'application.

Docsie vous permet d'avoir une navigation dynamique pour accéder facilement à l'information.

S'efforcer constamment d'améliorer et de mettre à jour

La création et l'utilisation de documents sont difficiles parce qu'ils sont rapidement oubliés par les personnes qui les ont produits ou qui en ont tiré profit. Les documents sont également confrontés à un certain nombre de défis tout au long de leur parcours.

Au fil du temps, la structure des dossiers prend l'allure d'un cimetière, les documents plus anciens ayant tendance à rester en bas de l'écran.

Veillez donc à revenir sur votre ancienne documentation et à y apporter des améliorations, et encouragez vos collègues à faire de même de temps en temps. Docsie vous permet de créer des mises à jour grâce à notre système avancé de gestion des versions, qui est simple et facile à mettre en œuvre.

Dernières réflexions :

Voulez-vous en savoir plus sur la manière de rédiger une documentation efficace ? Pour les professionnels de la documentation logicielle, il existe une multitude de blogs et d'informations ici.