Documentation technique : Le guide complet pour débutants avec exemples

Lorsque votre produit nécessite un minimum de compétences techniques pour démarrer, votre documentation est souvent la première et la dernière chance de convertir cet utilisateur en client.

Personne ne veut lire des milliers de mots ennuyeux remplis de jargon, ils veulent commencer à utiliser votre produit immédiatement.

Ce qui est difficile à réaliser avec la documentation technique, mais au cours des quinze dernières années de création d'outils pour le service client et la documentation, nous en avons appris suffisamment pour vous aider à y parvenir.

Une documentation technique facile à comprendre, à parcourir, à rechercher, et qui améliore le taux de conversion.

Dans ce guide, nous explorerons tout sur la documentation technique : des meilleurs exemples, des conseils d'écriture à la création de la vôtre.

Commençons !

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.

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 l'efficacité des coûts.

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

La documentation produit contient des informations sur le produit en cours de construction et donne des conseils 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 d'utilisation, 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 des processus comprend chaque élément de contenu créé concernant 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 typique des processus comprend des procédures opérationnelles standard, la documentation du projet, des plans de processus, des dates de test, des livres blancs, des comptes rendus de réunion, ainsi que la communication d'entreprise.

Meilleurs exemples de documentation technique pour vous inspirer

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

1. Documentation API Stripe

Si vous demandez aux développeurs quelle entreprise possède la meilleure documentation API, la réponse est généralement la même : Stripe.

Ce qui rend les docs de Stripe exceptionnelles, ce n'est pas seulement qu'elles sont complètes. C'est qu'elles donnent l'impression d'avoir été écrites par des développeurs qui utilisent réellement le produit, et non par des rédacteurs techniques suivant un modèle.

Stripe maintient un document interne de 20 pages sur la conception des API que chaque nouvel endpoint doit suivre (lequel).

Ils ont intégré la qualité de la documentation dans leur échelle de carrière d'ingénieur. Cette discipline se reflète dans chaque page.

Ce qu'il faut apprendre de l'exemple de Stripe :

• La disposition en trois colonnes maintient la navigation, l'explication et le code visibles simultanément.
• Lisible par défaut, technique si nécessaire : Pas d'introductions interminables. Les paramètres ont des types, des valeurs par défaut et des contraintes clairs. Les exemples utilisent de vraies valeurs au lieu de placeholders.
• Exemples de code dans sept langues : cURL, Node, Python, PHP, Ruby, Java et .NET. Ce sont également des exemples prêts pour la production.
• Fonctionnalité d'essai intégrée à la documentation : Exécutez des appels API directement depuis la page de référence en utilisant votre clé de test.
• Consistent URL structure and predictable patterns. Their technical document format follows a strict template:
  • Description (ce que fait l'endpoint, quand l'utiliser)
  • Endpoint (méthode HTTP + URL)
  • Exigences d'authentification
  • Tableau des paramètres (chemin, requête, corps)
  • Exemple de requête et de réponse
  • Codes d'erreur spécifiques à cet endpoint
  • Extraits de code d'exemple
• Clés API auto-remplies : lorsque vous êtes connecté, vos clés API de test apparaissent directement dans les exemples de code, éliminant une étape manuelle fastidieuse.
• Interaction de survol et de mise en surbrillance : survoler une description met en surbrillance la ligne de code correspondante, montrant exactement ce que fait chaque paramètre.

Ce qu'il faut surveiller

Bien que la documentation technique de Stripe soit très bonne, ce n'est pas quelque chose que tout le monde devrait répliquer.

Cela peut être décourageant pour les débutants. La quantité d'informations peut être intimidante.

Par exemple, un développeur débutant dans le domaine des paiements pourrait ne pas savoir par où commencer.

Stripe résout ce problème avec une section « Commencer », mais il est facile de la manquer si vous plongez directement dans la référence de l'API.

De plus, il n'y a aucun contenu vidéo intégré. Ce qui limite l'accessibilité pour les apprenants visuels.

2. Documentation Twilio

Twilio est confronté à un défi unique. Leurs produits (SMS, voix, vidéo, e-mail) sont conceptuellement simples mais comportent de nombreuses options de configuration.

Leur documentation trouve un équilibre entre permettre aux développeurs d'obtenir rapidement un prototype fonctionnel et expliquer les capacités complètes de la plateforme.

Chacun de leurs produits dispose d'un guide de démarrage rapide, d'une référence API et d'exemples de code dans plusieurs langues. Cela est logique car les clients de Twilio viennent souvent pour un produit et s'étendent à d'autres à mesure que leurs besoins augmentent.

Ce qu'il faut apprendre de l'exemple de Twilio :

• Des guides de démarrage rapide qui fonctionnent réellement en quelques minutes : Les guides supposent une configuration nulle et vous guident à travers la création d'un compte, l'obtention des identifiants, l'installation du SDK et l'exécution de votre premier appel API. Les instructions sont suffisamment spécifiques pour que vous puissiez les suivre sans avoir à consulter d'autres documents.
• Exemples de code dans six langues ou plus
• Le contexte avant le code : Avant de voir les paramètres de l'API, Twilio explique comment fonctionne le SMS programmable, quels sont les numéros de téléphone dans différents pays et comment choisir entre les codes courts et les codes longs. Cela aide les développeurs à prendre des décisions éclairées avant d'écrire du code.
• Guides de migration pour les transitions courantes
• Séparation claire entre l'API REST et les bibliothèques d'aide : La documentation du SDK est conservée séparément mais liée de manière proéminente.
• Widget de commentaires pour chaque section. Ce qui aide à améliorer la qualité de la documentation.

Ce qu'il faut surveiller

L'échelle crée des défis de navigation. Avec des milliers de pages couvrant des dizaines de produits, trouver le bon point de départ peut encore être difficile.

3. Notion

Vous devez l'accepter. Des outils comme Notion (outils avec des centaines de fonctionnalités et d'utilisations) nécessitent des compétences techniques pour en tirer le meilleur parti.

Là où la plupart des centres d'aide semblent conçus pour détourner les demandes de support plutôt que pour aider réellement les utilisateurs.

Le centre d'aide de Notion adopte l'approche opposée, traitant la documentation comme une extension de l'expérience produit elle-même.

Notion organise son contenu d'aide en trois couches distinctes :

• Documents de référence pour des réponses rapides à des questions spécifiques
• Guides pour des tutoriels plus longs organisés par fonction d'équipe (ingénierie, design, marketing, RH),
• Notion Academy pour des cours structurés avec des quiz et des certifications.

Cette approche à trois niveaux permet aux utilisateurs de choisir leur profondeur d'apprentissage, et cela fonctionne.

Ce qu'il faut apprendre de l'exemple de Notion :

• Architecture de contenu à trois niveaux (référence, guides, académie) répond à différents styles d'apprentissage et niveaux d'urgence à partir d'un seul centre d'aide.
• Illustrations personnalisées et identité visuelle font du centre d'aide une partie intégrante de la marque globale de Notion.
• Des guides organisés par fonction d'équipe (et non par simple fonctionnalité produit) aident les utilisateurs à trouver du contenu qui correspond à leur flux de travail et à leur rôle réels.
• Testeur d'API interactif intégré à la documentation permet aux développeurs d'essayer les points d'accès directement dans le navigateur.

Ce qu'il faut surveiller

Certains guides de Notion brouillent la frontière entre l'éducation et le marketing, en particulier autour des fonctionnalités d'IA, ce qui peut saper la confiance des lecteurs sceptiques.

4. API Slack

Ouvrez la documentation de l'API Slack et la première chose que vous remarquez est le ton. « Bonjour, cher développeur ! » vous accueille avec un emoji de vague, donnant le ton conversationnel qui règne sur tout le site. C'est un choix délibéré, et il fonctionne bien.

Slack a achevé une migration majeure de sa documentation début 2025. La nouvelle architecture organise le contenu en quatre catégories claires :

• Guides (explications conceptuelles)
• Référence (méthodes d'API, scopes, événements)
• Exemples (applications exécutables)
• Outils (framework Bolt, SDK, CLI)

L'objectif explicite de Slack est de passer de l'inscription au premier appel d'API en 15 minutes pour les développeurs débutants. Cet objectif façonne chaque décision de documentation, de l'emplacement des liens de démarrage rapide à la conception de leur testeur d'API interactif.

Ce qu'il faut retenir de l'exemple de Slack :

• Un ton conversationnel avec de la substance prouve que l'on peut être amical et précis simultanément, rendant le contenu technique plus accessible sans sacrifier la précision.
• Testeur d'API interactif intégré à la documentation permet aux développeurs d'essayer les points de terminaison directement dans le navigateur.
• Block Kit Builder fournit une interface visuelle par glisser-déposer pour construire des composants d'interface utilisateur, avec aperçu en direct et sortie JSON.
• Journal des modifications transparent
• Sandbox développeur : des environnements sandbox gratuits de niveau entreprise via le programme développeur offrent aux développeurs un espace de test sans risque.

Points à surveiller :

• Fragmentation de la plateforme : la distinction entre les applications classiques, les applications Slack, les applications de flux de travail et le constructeur de flux de travail n'est pas claire. Ce qui peut être très déroutant pour les nouveaux développeurs.
• Les extensions répétées des délais de dépréciation (le coucher de soleil des applications classiques a été repoussé plusieurs fois) érodent la confiance des développeurs dans la stabilité de la plateforme.
• La documentation pendant la période de migration existait simultanément à deux endroits, provoquant une confusion quant au site qui faisait autorité.

5. Documentation GitHub

Voici quelque chose d'inhabituel dans la documentation de GitHub : la documentation elle-même est open source.

Le dépôt de documentation GitHub a obtenu plus de 66 700 forks, ce qui en fait l'un des projets de documentation les plus forkés existants et un exemple concret de docs-as-code pratiqué à grande échelle.

La documentation GitHub couvre une énorme surface, des bases de Git et de la gestion de dépôts aux actions GitHub. Le contenu est organisé en 10 catégories principales sur la page d'accueil, avec un sélecteur de version.

La gestion de tout cela est une réalisation technique significative.

Ce qu'il faut retenir de l'exemple de la documentation GitHub :

• Contenu communautaire avec supervision éditoriale : Ce qui invite les contributions de la communauté et renforce la confiance par la transparence.
• La gestion de versions à source unique sert la documentation de huit versions de produits simultanées à partir d'un seul ensemble de fichiers.
• La recherche assistée par Copilot génère des réponses en langage naturel à partir de la documentation.
• Guides pratiques de dépannage

6. Ahrefs

La base de connaissances d'Ahrefs est organisée en fonction de ses fonctionnalités : Site Explorer, Keywords Explorer, Rank Tracker, Site Audit, Content Explorer, et autres.

Chaque collection affiche les avatars des auteurs et le nombre d'articles, lui donnant une touche personnelle et orientée équipe.

La base de connaissances n'est qu'une partie du plus grand écosystème éducatif d'Ahrefs, et ce n'est même pas la meilleure partie.

Ahrefs Academy propose des cours vidéo structurés gratuits (fondamentaux du SEO, marketing de contenu, blogging pour les entreprises) avec certification. Et le blog Ahrefs Blog publie des guides SEO basés sur des données.

Le centre d'aide traite les questions spécifiques au produit tandis que le blog, l'académie et YouTube traitent de l'éducation plus générale : cette division du travail est une stratégie qui mérite d'être copiée.

Ce qu'il faut apprendre de l'exemple d'Ahrefs :

• Écosystème éducatif à plusieurs niveaux : Centre d'aide pour les questions produit, académie pour l'apprentissage structuré, blog pour le leadership éclairé, YouTube pour les tutoriels visuels.
• Organisation centrée sur l'outil reflète la navigation propre au produit, rendant intuitif pour les utilisateurs de trouver des articles sur la fonctionnalité qu'ils utilisent actuellement.
• Articles riches en captures d'écran avec annotations fournissent des conseils contextuels.
• FAQ sur la page d'accueil répond immédiatement aux questions les plus courantes, réduisant la friction de recherche.
• Puissant widget de chat permet aux utilisateurs de rechercher dans la base de connaissances ou de contacter l'équipe de support.

Ahrefs est le meilleur exemple de création d'un écosystème éducatif autour de votre produit. Leurs articles de blog, leur académie et leurs vidéos YouTube font tous partie de leur stratégie de documentation ciblant différents publics.

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

É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.

Généralement, la documentation destinée aux clients est créée par un rédacteur technique, 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 de documentation et c'est ce que nous utiliserons pour ce tutoriel.

WordPress est une plateforme CMS gratuite, 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 de l'installer 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 d'écriture 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 approfondi est précis, concis et pertinent. Et c'est là qu'un système de gestion de documentation technique tel que Heroic KB peut 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 Service Desk du coût par ticket par ThinkHDI ↩︎