Comment créer une documentation technique (guide étape par étape)

Qu'est-ce que la documentation technique ?

La documentation technique est un type de matériel écrit qui contient des informations détaillées sur la façon d'utiliser, de construire, de maintenir et de dépanner un produit, un service ou un système.

Par exemple, dans le développement logiciel, la documentation technique est un terme général qui fait référence à tous les guides et autres contenus liés au développement et aux fonctionnalités de produits spécifiques.

Voici la principale différence entre la documentation normale (ou générale) et la documentation technique :

Documentation normale	Documentation technique
Fournit des informations générales dans un langage plus simple.	Fournit des informations approfondies, incluant souvent des termes techniques, des extraits de code, des diagrammes et des exemples.
Généralement créée pour fournir un aperçu rapide d'un produit ou d'un service sous forme de guides d'utilisation ou de FAQ.	Comprend des instructions sur la façon d'utiliser, de construire, de maintenir et de dépanner un produit ou un système. Quelques exemples sont la documentation API, les guides d'architecture ou les documents de conception de système.
Conçue pour les utilisateurs finaux, les clients ou toute personne ayant des connaissances techniques limitées.	Conçue pour les développeurs, les ingénieurs ou les professionnels de l'informatique.

Et il y a tellement plus à découvrir sur la documentation technique dans ce guide.

Pourquoi la documentation technique est-elle importante ?

La documentation technique est un atout qui sert divers intervenants en les aidant à comprendre le produit et son développement et à être sur la même longueur d'onde.

Tout en offrant également aux clients un moyen de résoudre les problèmes grâce à un canal d'auto-assistance.

La documentation technique est devenue cruciale pour fournir un service client de premier ordre tout en maintenant une rentabilité.

Une étude de ThinkHDI¹ montre que les canaux d'auto-assistance coûtent en moyenne seulement 2,37 $, tandis que les canaux individuels coûtent en moyenne 15 à 37 $.

Voici d'autres avantages de la documentation technique :

1. Améliore la communication et la collaboration entre les départements, en servant de source d'information unique.
2. Augmente l'efficacité et la productivité
3. Améliore la satisfaction client grâce aux canaux d'auto-assistance et aux réponses rapides.
4. Réduit le coût du service client en diminuant le nombre de tickets de support client.
5. Réduit la courbe d'apprentissage et aide les nouveaux employés à s'intégrer.
6. Permet une prise de décision rapide
7. Fournit une feuille de route pour les projets futurs
8. Enregistrer les idées
9. Favorise la rétention des connaissances

Types de documentation technique

La documentation technique peut être divisée en deux types principaux :

1. Documentation produit comprend la documentation système et utilisateur.
2. Documentation de processus comprend les références de processus et les opérations internes

1. Documentation produit

Documentation produit contient des informations sur le produit en cours de construction et donne des indications sur ses cas d'utilisation.

Ces informations comprennent les exigences du produit, la logique métier, les spécifications techniques et les guides utilisateur.

Documentation système

La documentation système offre un aperçu du cadre de création du produit et permet aux développeurs de produits et aux autres personnes impliquées de comprendre la technologie sous-jacente.

Généralement, elle comprend les exigences, les spécifications, le code source, la conception de l'architecture, les rapports de validation, les détails d'authentification et de test, ainsi que les instructions de maintenance.

Documentation utilisateur

La documentation utilisateur est conçue pour ceux qui utilisent le produit. Cependant, les types d'utilisateurs peuvent varier. C'est pourquoi vous devez créer ces documents en fonction de diverses catégories d'utilisation et degrés de compétence.

Habituellement, la documentation utilisateur s'adresse à deux segments principaux : les administrateurs système et les utilisateurs finaux.

Ce type de documentation comprend des guides pratiques, des manuels utilisateur, des guides d'installation, des documents de dépannage, des manuels d'instructions, des foires aux questions et des guides d'aide.

2. Documentation de processus

La documentation de processus comprend chaque élément de contenu créé en ce qui concerne la construction et la gestion des processus impliquant l'ingénierie des produits.

La différence essentielle entre la documentation de processus et la documentation de produit est que la première documente les procédures d'ingénierie tandis que la seconde explique le produit.

La raison de maintenir la documentation de processus est d'améliorer l'organisation et la planification de la phase d'ingénierie.

Ce type de documentation nécessite une préparation et une stratégie avant de commencer le processus et également pendant la construction du produit.

La documentation de processus typique comprend les procédures d'exploitation standard, la documentation de projet, les plans de processus, les dates de test, les livres blancs, les comptes rendus de réunions et également la communication d'entreprise.

Exemples de documentation technique

Voici quelques exemples de bonne documentation technique et ce qu'il faut en apprendre.

1. Documentation Spren

Spren est une entreprise qui propose des API pour les connexions avec des applications mobiles liées à la santé afin de fournir des informations biométriques personnalisées et précises.

Mais c'est un processus délicat, et il nécessite des articles techniques simples à comprendre et produits par un professionnel. Ainsi, les entreprises d'applications peuvent intégrer la solution de manière transparente dans leurs cycles de projet respectifs.

C'est pourquoi la documentation de Spren est un excellent exemple de documentation technique bien faite. Elle fournit une pléthore de visuels et d'illustrations pour engager les clients, rendant la documentation plus facile à comprendre.

2. Documentation Spryker

La documentation de Spryker doit s'adresser à divers groupes d'utilisateurs, y compris les programmeurs et les techniciens responsables de l'installation et de la maintenance du logiciel. Et aussi le client cible qui utilisera Spryker pour exploiter sa boutique en ligne.

Cela implique que leur documentation doit contenir du contenu qui répond à des besoins divers. De plus, ils devraient la développer en fonction des compétences techniques de l'utilisateur final ciblé.

Et c'est exactement ce qu'ils ont fait. Ils ont organisé la documentation par groupes d'utilisateurs.

Comme on peut le voir, chaque personne utilisant la documentation doit d'abord déterminer sa catégorie parmi les trois types d'audiences (utilisateurs métier, développeurs, ingénieurs cloud) puis sélectionner une collection de guides.

Une fois que l'utilisateur entre dans la zone appropriée, il verra des guides conçus pour son rôle et son niveau de compétence technique.

Comme vous pouvez le voir dans l'exemple de documentation technique ci-dessus, l'objectif principal est de s'assurer que les programmeurs et les autres utilisateurs peuvent facilement trouver les guides qu'ils recherchent.

3. Aide et documentation Metric Insights

Metric Insights est un système d'intelligence de poussée qui utilise les informations d'interaction de vos visiteurs et d'autres détails pour vous fournir des idées pratiques pour améliorer votre site.

Avec leur documentation technique pour les utilisateurs, vous pouvez voir comment ils ont couvert plusieurs scénarios.

De l'utilisation d'un produit du point de vue d'un utilisateur régulier à celui d'un administrateur.

Guides sur le dépannage, la maintenance et les notes de version. De plus, les guides sont très détaillés et visuellement riches.

Comment créer une documentation technique

Étape 1 : Décider des exigences et du type de contenu à créer

Lors de la planification de la documentation technique, réfléchissez à l'utilité qu'elle peut avoir pour votre entreprise, la quantité de documentation nécessaire et vaut-il la peine d'y investir du temps et de l'argent ?

Ne pas avoir suffisamment de documentation technique peut affecter l'utilité globale. D'un autre côté, avoir plus d'informations que nécessaire embrouillera les choses pour vous.

Voici les types de contenu que vous pouvez planifier avec votre documentation technique :

• Portée et planification du produit
• Documentation système
• Code source, documentation API
• Guides de dépannage et de maintenance
• Journaux des modifications
• Cas d'utilisation
• Manuels d'utilisation
• Documentation des processus

Étape 2 : Rédaction de la documentation technique

L'utilité de votre documentation technique dépend de la qualité de rédaction et d'enseignement des guides, surtout si vous les créez pour résoudre les problèmes des clients.

Voici quelques conseils pour rédiger des documents techniques de qualité :

2.1. Écrivez pour votre public

Comprendre le public est très important. Par exemple, servir de la nourriture non végétarienne à un végétarien ne fonctionnerait pas, n'est-ce pas ?

Il en va de même pour tout type de documentation.

Vous devez adapter vos méthodes d'enseignement en fonction de la personne à qui vous écrivez.

Regardons l'exemple WordPress :

Exemple de documentation centrée sur le client WordPress.

Exemple de documentation technique WordPress.

La différence ici ?

Public : La documentation normale est créée pour les éditeurs, les blogueurs, les gestionnaires ou toute personne sans connaissances techniques.

Alors que la documentation technique est créée pour les développeurs, les ingénieurs, les opérateurs de serveurs ou les utilisateurs techniques.

Différence de contenu : La documentation normale est très simple, directe et n'inclut pas de contenu technique.

Alors que la documentation technique contient beaucoup d'informations, de ressources liées, de code et d'exemples concrets sur la façon dont quelqu'un peut utiliser des fonctions ou des paramètres spécifiques.

Expérience nécessaire : La documentation normale peut être créée par quiconque ayant des compétences en écriture et un peu de recherche sur le produit, tandis que la documentation technique nécessite l'implication d'un développeur ou d'un expert pour être précise et utile.

2.2. Testez le produit, le code ou la recherche de manière approfondie

La documentation est créée pour aider les clients ou pour mieux comprendre la situation.

Habituellement, la documentation destinée aux clients est créée par un rédacteur de documentation, des agents du support client ou un rédacteur. Et cela fonctionne.

Mais il n'en va pas de même pour la documentation technique. Vous avez besoin de plus qu'une compréhension du produit ou du code.

Des aperçus qui ne peuvent être obtenus que par une implication et des tests appropriés.

2.3. Commencez par un plan

Créer un plan avant tout guide ou tutoriel ne prend pas beaucoup de temps (généralement 1 heure), mais cela peut faire gagner beaucoup de temps dans les étapes ultérieures de création de contenu.

Vous êtes-vous déjà demandé pourquoi vos articles/guides ne sonnent pas bien, ne fonctionnent pas ou ne donnent pas cette touche professionnelle ?

Parce qu'ils n’ont pas été bien planifiés.

Voici quelques éléments que vous pouvez inclure dans les plans de vos documents techniques :

1. Titre
2. Mots-clés ciblés ou termes de recherche les plus courants
3. User Stories (En tant qu'utilisateur, je veux, afin de formule)
4. Public, à qui s'adresse-t-il
5. Type d'article : Comment faire, liste, vidéo, critique ou comparaison par exemple.
6. Objectifs
7. Articles de référence
8. Nombre de mots attendu
9. Plan succinct (ou table des matières) : Portée de ce que vous couvrirez, ressources existantes et structure de l'article.

2.4. Restez simple (utilisez des modèles) et n'ajoutez pas de remplissage

L'ajout des informations strictement nécessaires devrait être l'un des points principaux de votre guide de style de rédaction de documentation technique.

De plus, en fonction de votre expérience et de vos tests, vous pouvez créer des modèles (modèles de type d'article) qui fonctionnent le mieux pour le type de contenu que vous créez.

1. Évitez d'utiliser des termes techniques, et si vous ne pouvez absolument pas l'éviter, expliquez-les
2. Gardez les paragraphes courts
3. Structurez le contenu avec des titres, des sous-titres, des listes, des tableaux et des images
4. Évitez d'en faire trop et supprimez le contenu superflu autant que possible

2.5. Utilisez des aides visuelles

Les visuels font la différence, surtout pour rendre les concepts techniques faciles à comprendre.

Il peut s'agir d'une simple capture d'écran, d'un croquis, d'un dessin ou d'un graphique bien conçu. Tant que cela aide !

2.6. Ajoutez des exemples et des références chaque fois que possible

La documentation technique consiste à documenter et à décomposer des informations complexes.

L'ajout d'exemples et de liens vers des ressources pertinentes chaque fois que possible y contribue.

Vous pouvez ajouter des exemples pour montrer :

• Utilisations du code (comment une fonction spécifique ou un paramètre peut être utilisé)
• Cas d'utilisation de produits ou de logiciels. Surtout s'il existe plusieurs possibilités.
• Comment une chose ou une fonctionnalité particulière a été implémentée, ou comment un concurrent l'a fait.

2.7. Faites-le relire

Impliquez les développeurs, les ingénieurs et les membres de l'équipe dans le processus de documentation pour mieux comprendre la solution.

La création d'articles techniques nécessite la participation collective de tous les membres du groupe.

Une fois que vous avez préparé quelques articles techniques, montrez-les à vos collègues et recueillez leurs avis.

Pour simplifier les choses, utilisez des logiciels de collaboration comme les tableaux Kanban, Slack et Google Docs.

2.8. Créez un guide de style de rédaction technique

Lorsque vous commencez à créer votre contenu technique, créez un guide de style de rédaction qui vous convient le mieux.

Cela aidera à conserver les connaissances, à créer de la cohérence et à maintenir la qualité du contenu.

Par exemple, votre guide de style peut inclure :

1. Profil de l'audience ou audience cible
2. Style d'écriture et ton
3. Règles de grammaire et d'usage
4. Lignes directrices de formatage terminologie
5. Structure du document
6. Lignes directrices visuelles
7. Normes d'accessibilité
8. Politiques sur les liens et les références externes
9. Processus de révision et d'approbation
10. Outils et ressources

Nous avons beaucoup parlé des guides de style dans notre Guide de style de la base de connaissances, qui vous donnera un bon point de départ.

Étape 3 : Création d'un site Web de documentation technique

🤯, je sais, je sais.

Si vous avez suivi le guide jusqu'à présent, il y a beaucoup à assimiler. Mais je vous recommande vivement de passer du temps à rassembler votre contenu.

Parce que c'est ce qui rendra votre documentation technique normale pour vous et vos utilisateurs, pas technique.

Rappelez-vous, vous n'avez pas à viser le meilleur dès le départ, car l'expérience, les tests et les commentaires sont très importants pour créer quelque chose d'utile.

L'amélioration constante est la clé ici. Nous avons maintenant besoin d'un site Web ou d'une plateforme pour publier le contenu créé.

3.1. Créer un site Web WordPress

Nous allons créer un site Web ou un portail de documentation technique dédié, où vous pourrez héberger et maintenir tous vos documents privés et publics.

Pourquoi créer un site Web pour la documentation ?

1. Image de marque personnalisée
2. Meilleure expérience utilisateur
3. Accès centralisé
4. Fonctionnalités avancées comme l'intégration, l'analyse, le contrôle de version et la gestion.
5. Contrôle complet

Je recommande vivement WordPress avec Heroic Knowledge Base (Heroic KB) pour le site Web de documentation et c'est ce que nous utiliserons pour ce tutoriel.

WordPress est gratuit, open source et la plateforme CMS la plus populaire pour la documentation.

Alors que Heroic KB est un plugin WordPress premium pour créer tout type de site Web de documentation avec.

Si vous souhaitez une solution gratuite et disposez d'un budget ou de capacités de développement, vous pouvez utiliser des solutions comme MkDocs.

Maintenant, pour créer un site Web WordPress, vous pouvez l'installer sur n'importe quel type de service d'hébergement (y compris l'hébergement Web, l'hébergement cloud et les serveurs dédiés).

Pour simplifier les choses, utilisez des plateformes d'hébergement WordPress gérées comme Kinsta.

De plus, consultez ce tutoriel si vous prévoyez d'installer WordPress manuellement, ou demandez simplement à votre fournisseur d'hébergement d'installer WordPress pour vous.

3.2. Créer un site Web de documentation

Maintenant que vous avez un site WordPress prêt, installez le plugin Heroic KB pour obtenir les fonctionnalités nécessaires à votre portail de documentation.

Téléchargez le plugin Heroic KB en l'achetant ici.

1. Rendez-vous sur le Tableau de bord WordPress (auquel vous pouvez accéder en ajoutant /wp-admin à la fin de l'URL de votre site web)
2. Cliquez ou survolez Extensions → Ajouter une extension.
3. Cliquez sur le bouton Téléverser une extension.
4. Choisissez un fichier de plugin Heroic KB téléchargé.
5. Cliquez sur le bouton Installer maintenant.
6. Après l'installation, activez l'extension.

Une fois le plugin activé, un assistant de configuration Heroic Knowledge Base vous sera présenté.

Suivez les instructions pour importer le site de démonstration comme indiqué ici : https://heroickb.herothemes.com/

Remarque : Vous pouvez accéder à l'Assistant de configuration depuis la section Extensions si vous ne l'avez pas terminé pendant le processus d'installation.

Votre site web de documentation est prêt à ce stade, et vous pouvez le consulter depuis le frontend à l'adresse votredomaine.com/knowledge-base/.

3.3. Accès et rôles des utilisateurs

Avec WordPress et Heroic KB, vous disposez de toutes les options nécessaires pour gérer les accès et les rôles des utilisateurs. Vous permettant de créer des documentations internes ou publiques.

Les utilisateurs peuvent être gérés via WordPress → Utilisateurs. Vous pouvez ajouter de nouveaux utilisateurs manuellement ou activer une option WordPress pour autoriser l'enregistrement de nouveaux utilisateurs.

Mettez à jour les paramètres de Heroic KB pour que la documentation soit réservée à un usage interne, ou vous avez la possibilité pour chaque article de le rendre interne ou public.

WordPress → Heroic KB → Paramètres

3.4. Personnalisation

Avec un logiciel de documentation technique comme Heroic KB, vous avez toutes les options nécessaires pour personnaliser la documentation selon le style de votre marque ou vos préférences.

Tous les paramètres sont accessibles depuis WordPress → Heroic KB → Paramètres.

Par exemple, pour mettre à jour le schéma de couleurs de la documentation :

Pour mettre à jour les paramètres de mise en page :

Une personnalisation plus poussée peut être effectuée avec les thèmes WordPress ou du code personnalisé.

Avec un achat Heroic KB, vous obtenez un thème premium Heroic KnowAll qui débloque des possibilités de personnalisation illimitées sans écrire une seule ligne de code.

Étape 4 : Publication et gestion des documents

Maintenant que nous avons un contenu et un portail prêts, il ne vous reste plus qu'à ajouter et publier votre contenu.

Vous pouvez gérer tous vos articles, catégories et tags depuis WordPress → Heroic KB.

Pour ajouter un nouvel article, cliquez ou survolez Heroic KB → Ajouter un nouvel article.

Et voici à quoi ressemblera votre écran de création d'article :

C'est un éditeur très facile à utiliser et flexible une fois que vous commencez à le maîtriser.

De plus, vous obtenez des blocs supplémentaires de Heroic KB pour créer facilement une table des matières, un basculeur, un accordéon, des onglets, un bloc de code, ou pour partager des informations importantes.

Tout le style peut être géré via les thèmes WordPress ou via du code personnalisé.

Étape 5 : Continuer à optimiser

La rédaction de documentation technique ne s'arrête pas à la publication du contenu.

C'est un processus d'amélioration continue, utilisant la documentation pour bâtir les connaissances de votre entreprise, éviter de réinventer la roue et rationaliser les processus.

Pour commencer, voici comment vous pouvez optimiser votre documentation technique :

1. Simplifiez la création et la gestion de contenu
2. Créez et améliorez les directives de documentation technique en fonction des retours des utilisateurs
3. Assurez une navigation et un accès faciles à la documentation
4. Optimisation SEO
5. Effectuez des sauvegardes fréquentes

Heroic KB et WordPress disposent de fonctionnalités intégrées pour améliorer la documentation.

Fonctionnalités telles que des analyses puissantes, un système de feedback, une structure de site Web conviviale pour le SEO et des intégrations, des options éditoriales et un contrôle de révision.

Outils et logiciels de documentation technique pour vous aider

Je serai bref ici car nous avons déjà des guides très détaillés sur les outils de documentation technique et les outils de rédaction technique.

Ces outils recommandés vous aideront grandement à créer, gérer et optimiser la documentation technique.

1. WordPress + Heroic KB

Heroic KB est un système de documentation technique populaire, économique et collaboratif. Il convient à un large éventail d'industries et de produits.

Cela répondra facilement à la plupart des fonctionnalités requises pour votre documentation technique.

2. Convertisseur Mammoth .docx

Un plugin WordPress qui vous permet d'importer facilement des documents pour créer des articles et des pages.

Complétez votre article avec Google Docs et publiez-le avec WordPress en moins de 5 minutes avec cet outil. C'est aussi simple que cela de publier du contenu avec WordPress.

3. Github

Il y a de fortes chances que vous connaissiez déjà celui-ci. Vous pouvez également l'utiliser pour la documentation technique. Il est livré avec sa plateforme wiki native, ce qui est bien pour 5 à 20 pièces de documentation.

4. Figma

C'est un logiciel de conception basé sur le web, facile à utiliser et très flexible.

Similaire à WordPress, il dispose de tonnes de plugins pour améliorer ses fonctionnalités, de modèles pour faciliter la création graphique rapide et de fonctionnalités de collaboration. C'est l'un des meilleurs outils gratuits disponibles. Essayez-le !

5. Google Docs

Vous aurez besoin d'un moyen facile de créer du contenu et de collaborer avec l'équipe en même temps, et Google Docs est le meilleur pour cela.

6. FastStone Capture

Un outil premium pour capturer et enregistrer des écrans. Vous pouvez ajouter des annotations sur les images et les modifier avec d'autres fonctionnalités étonnantes. Il est livré avec une licence à vie, ce qui en vaut totalement la peine !

7. MkDocs

Une excellente plateforme pour créer gratuitement des sites web de documentation technique statiques. Il dispose de nombreux bons thèmes et plugins pour améliorer l'apparence générale et la fonctionnalité, mais il nécessite des capacités de développement.

Foire aux questions sur la documentation technique

Voici nos questions les plus fréquemment posées concernant la documentation technique, ainsi que leurs réponses.

Quel est le but de la documentation technique ?

Le but de la documentation technique est de fournir des informations sur un produit, un système ou un service qui est utilisé par un public technique ou non technique. Cette documentation aide les utilisateurs à comprendre comment le produit fonctionne, comment l'installer, l'utiliser et le dépanner, et comment réparer ou remplacer des pièces si nécessaire.

La documentation technique sert également de référence aux ingénieurs, développeurs et autres professionnels qui travaillent sur le produit. Elle contribue à assurer la cohérence et la standardisation, ainsi qu'à fournir un historique du développement et de l'évolution du produit.

Comment organiser et structurer la documentation technique ?

Voici quelques bonnes pratiques pour organiser et structurer la documentation technique :

• Commencez par une table des matières ou un index pour donner un aperçu des sujets abordés.
• Divisez la documentation en sections claires et utilisez des titres et des sous-titres pour guider le lecteur.
• Utilisez un langage clair et concis et évitez le jargon technique, sauf s'il est inévitable et bien expliqué.
• Incluez des exemples et des aides visuelles, tels que des diagrammes et des captures d'écran, pour aider à expliquer les concepts complexes.
• Utilisez un format et un style cohérents dans toute la documentation, y compris la taille et le style de la police, les titres et l'espacement des paragraphes.
• Fournissez une fonction de recherche ou un index pour faciliter la navigation, en particulier pour les ensembles de documentation plus longs.

Quelle est la différence entre la documentation technique et la documentation utilisateur ?

La documentation technique et la documentation utilisateur sont toutes deux des formes de documentation écrite qui fournissent des informations sur un produit ou un service. Cependant, elles ont des objectifs et des publics cibles différents.

La documentation technique est destinée aux utilisateurs techniques, tels que les ingénieurs, les développeurs et les professionnels de l'informatique. Elle fournit des informations détaillées sur la conception, l'architecture et les spécifications techniques du produit, et est utilisée pour le dépannage et la maintenance.

La documentation utilisateur, quant à elle, est destinée aux utilisateurs finaux, tels que les clients et les employés qui utilisent le produit ou le service. Elle fournit des informations sur la façon d'utiliser le produit, y compris des instructions étape par étape et des aides visuelles.

En résumé

Les connaissances techniques sont un atout essentiel pour les lecteurs. Vous devez développer et publier des articles techniques utiles pour tous, y compris des documents pour les développeurs de logiciels et l'équipe de test, ainsi que la documentation utilisateur.

Pourtant, en raison des cycles de développement rapides des produits, il peut être difficile de rendre votre documentation technique disponible et attrayante.

Un portail de connaissances techniques complet est précis, concis et pertinent. Et c'est là qu'un système de gestion de documentation technique tel que Heroic KB peut vous aider.

Grâce aux capacités de gestion de contenu et de travail d'équipe de Heroic KB, vous pouvez facilement améliorer votre processus de rédaction et vos guides techniques. Et stimuler la productivité et l'engagement des utilisateurs de votre organisation.

Ressources mentionnées dans ce tutoriel

1. Comprendre la métrique du centre de services du coût par ticket par ThinkHDI ↩︎