Qu'est-ce que la documentation d'un logiciel ? Types et meilleures pratiques pour commencer

Si vous voulez que les développeurs et les utilisateurs finaux tirent le maximum de valeur de votre logiciel, vous devez créer une documentation logicielle de haute qualité.

Mais qu 'est-ce que la documentation d'un logiciel et comment pouvez-vous la créer pour votre projet ?

Dans ce billet, nous allons examiner tout ce qu'il faut savoir sur la documentation des logiciels, y compris ce qui suit :

Allons-y !

Qu'est-ce que la documentation d'un logiciel ?

La documentation d'un logiciel est un contenu qui aide les utilisateurs finaux, les développeurs et/ou vos employés à comprendre votre logiciel et à l'utiliser pour atteindre efficacement leurs objectifs.

En règle générale, vous publiez la documentation du logiciel sur votre site web. Les internautes peuvent alors y accéder pour en savoir plus sur votre logiciel et son fonctionnement.

Dans le cadre de cette définition générale de la documentation logicielle, il existe différents types de documentation logicielle. C'est ce que nous allons voir maintenant.

Les différents types de documentation sur les logiciels

Les différents types de documentation sur les logiciels peuvent être classés en quelques grandes catégories.

La première considération est de savoir à quel type de personne la documentation est destinée :

• Documentation utilisateur - il s'agit de la documentation que vous avez créée pour l'utilisateur final du produit. Elle les aide à comprendre comment utiliser votre logiciel du point de vue d'un utilisateur normal, qui peut ou non avoir des connaissances techniques particulières.
• Documentation destinée aux développeurs - il s'agit d'une documentation logicielle plus technique que vous avez créée à l'intention des développeurs, telle que la documentation relative à l'API.

La deuxième considération est de savoir si la documentation est destinée à un public externe ou interne :

• Documentation externe du logiciel - il s'agit de la documentation publique que vous avez créée pour aider vos utilisateurs.
• Documentation interne du logiciel - il s'agit d'une documentation privée que vous avez créée pour vos employés afin de les aider à travailler plus efficacement et à comprendre les détails clés.(Guide complet de la documentation interne)

Par exemple, vous pouvez disposer d'un ensemble de documents à l'intention de vos équipes internes pour les aider à travailler sur le logiciel et d'un autre ensemble de documents à l'intention des développeurs externes.

Détaillons un peu plus ces types de documentation logicielle...

Exemples de documentation de logiciels pour la documentation du développeur

• Documentation de l'API - montrer aux développeurs comment interagir avec l'API de votre logiciel.
• Readme - présente votre logiciel et explique ce qu'il fait - c'est généralement la première chose que les gens lisent.
• Notes de version - documentent les nouvelles versions de votre logiciel, y compris les changements importants.
• Documentation sur l'architecture - montre la structure de votre logiciel, éventuellement à l'aide de diagrammes.
• Documentation du modèle de données - documenter les différentes structures de données de votre logiciel, y compris les relations entre les différentes structures de données.
• Documentation des processus - documenter les processus clés tels que les rapports de bogues, les feuilles de route, l'assurance qualité, les protocoles d'essai, etc.

Pour un véritable exemple de documentation logicielle axée sur les développeurs, vous pouvez consulter la documentation "Developers" de Gravity Forms qui couvre divers sujets tels que :

• Crochets PHP (pour WordPress)
• Objets de données
• API PHP
• Base de données
• API REST

Par exemple, voici à quoi ressemble la documentation de l'API REST:

Exemples de documentation de logiciels pour la documentation de l'utilisateur

• Guide de démarrage - montre aux utilisateurs comment utiliser rapidement votre logiciel.
• Tutoriels pour des cas d'utilisation spécifiques - des tutoriels plus spécifiques pour accomplir des tâches particulières.
• Glossaires/manuels de référence - aident les utilisateurs à comprendre les termes clés et les détails. Nous avons un guide sur la création de glossaires avec WordPress si vous voulez en savoir plus.
• FAQ - réponses aux questions les plus fréquemment posées.

Pour un exemple concret de ce à quoi pourrait ressembler une documentation logicielle plus orientée vers l'utilisateur, vous pouvez vous tourner vers le même exemple de Gravity Forms que nous avons cité plus haut.

Si vous regardez les articles de Gravity Forms plus axés sur l'utilisateur, vous verrez de nombreux tutoriels étape par étape sur la façon de réaliser des tâches en utilisant l'interface du logiciel, ainsi que des glossaires et des explications sur les fonctionnalités clés.

Par rapport à la documentation d'un logiciel de développement, vous verrez plus de captures d'écran et d'explications en langage clair et beaucoup moins de blocs de code.

Comment publier la documentation d'un logiciel : Trois meilleurs outils de documentation logicielle

Pour publier la documentation de votre logiciel sur votre site web, vous aurez besoin d'un outil de documentation dédié ou d'un système de gestion des connaissances.

Dans cette section, nous aborderons rapidement quelques-uns des meilleurs outils de documentation logicielle. Puis, dans la section suivante, nous passerons en revue les meilleures pratiques pour créer une documentation de qualité.

Si vous souhaitez approfondir la question, vous pouvez lire nos guides complets sur les meilleurs outils de documentation et les meilleurs logiciels de documentation technique.

Base de connaissances héroïques

Heroic Knowledge Base est un plugin de documentation et de base de connaissances pour le célèbre logiciel libre WordPress.

Avec Heroic Knowledge Base, vous pouvez auto-héberger votre documentation et garder un contrôle total, tout en accédant à toutes les fonctionnalités dont vous avez besoin pour créer une documentation logicielle efficace.

Voici quelques-unes des fonctionnalités de base que vous obtenez avec Heroic Knowledge Base :

• Éditeur de contenu flexible, comprenant des blocs intégrés pour les appels et d'autres détails stylistiques importants.
• Table des matières automatique permettant aux utilisateurs de voir rapidement le contenu d'un article de documentation et d'accéder à des sections spécifiques.
• Contrôle des révisions et historique des versions via le système de révision natif de WordPress.
• Fonctionnalités de découverte de contenu comprenant la recherche Ajax en temps réel avec des suggestions en direct, des catégories et plus encore.
• Système de rétroaction des utilisateurs qui permet aux gens d'évaluer les articles comme étant utiles ou non et de partager leur rétroaction.
• L'analyse des recherches vous permet de savoir ce que les utilisateurs recherchent, ainsi que les termes de recherche qui n'aboutissent à aucun résultat.
• Widget de réponses instantanées permettant aux utilisateurs de rechercher et d'accéder à la documentation du logiciel à partir de n'importe quel endroit de votre site.

Comme Heroic Knowledge Base et WordPress sont tous deux auto-hébergés et open-source, vous êtes également libre de modifier votre installation selon vos besoins.

Vous pouvez le rendre public ou restreindre l'accès à votre documentation à l'aide de différentes tactiques telles que les mots de passe, les comptes d'utilisateurs, les adresses IP, un intranet, etc.

Heroic Knowledge Base est disponible à partir de 149 $ par an.

Lire les documents

Read the Docs est un outil de documentation qui a pour but de vous aider à créer de la documentation pour les développeurs.

Si vous vous concentrez spécifiquement sur la création de documentation technique pour les développeurs, il peut s'agir d'une autre option intéressante.

Vous pouvez gérer votre contenu et l'historique des révisions à l'aide de Git, puis déployer vos documents dans une interface frontale.

Voici quelques-unes des autres caractéristiques notables de Read the Docs :

• Analyses intégrées pour savoir ce que vos utilisateurs lisent et recherchent.
• Prend en charge plusieurs versions simultanées, ce qui peut être utile si vous proposez plusieurs versions de votre logiciel - par exemple, un ensemble de documents pour la version 1.0 et un autre pour la version 2.0.
• Exporter la documentation dans différents formats, notamment PDF, HTML et epub.
• Suggestions de recherche en direct pour aider les utilisateurs à trouver des documents.

L'utilisation de Read the Docs est gratuite si vous avez un projet de logiciel libre.

Pour les logiciels commerciaux, il existe un service payant "Read the Docs for Business" à partir de 50 dollars par mois.

GitBook

GitBook est un autre outil de documentation technique de logiciels qui vous permet de gérer votre documentation à l'aide de Git, avec un support pour les dépôts GitHub et GitLab.

Si vous ne souhaitez pas utiliser Git, GitBook vous permet également de créer votre documentation à l'aide d'un éditeur de texte ou de l'importer à partir de fichiers markdown ou .doc.

Voici d'autres fonctionnalités notables offertes par GitBook :

• Contrôle de version pour suivre les révisions et l'historique des versions.
• L'édition en équipe en direct est utile si vous avez besoin de faire collaborer plusieurs auteurs sur des articles.
• Organiser les articles en utilisant des "espaces" et des "collections" - chaque espace peut contenir plusieurs collections.
• L'option d'exportation PDF permet aux utilisateurs d'exporter facilement votre documentation au format PDF.

GitBook est gratuit pour les organisations à but non lucratif ou les projets open-source.

Pour les projets de logiciels commerciaux, GitBook commence à 8 $ par utilisateur et par mois, avec un minimum de 5 utilisateurs. Cela signifie que le tarif mensuel le moins cher est de 40 $ par mois.

Bonnes pratiques pour la création de documentation sur les logiciels

Pour terminer, examinons les meilleures pratiques en matière de documentation logicielle pour vous aider à créer une documentation efficace.

Réfléchir aux objectifs et aux besoins des utilisateurs

Lorsque vous rédigez un article sur la documentation d'un logiciel, il est important de commencer par répondre à quelques questions de base :

• Qui est l'utilisateur pour lequel vous écrivez ?
• Qu'est-ce que l'utilisateur essaie d'accomplir ?
• Quel est le niveau de connaissances techniques de l'utilisateur ?

Les réponses à ces questions vous aideront à déterminer le contenu à couvrir et à structurer l'article de la manière la plus optimale possible.

Par exemple, disons que vous proposez un logiciel de planification des médias sociaux et que vous écrivez un article qui aide les responsables des médias sociaux à planifier leur premier message sur les médias sociaux.

Lorsque vous rédigez la documentation de votre logiciel, vous devez vous efforcer de montrer la manière la plus simple pour un utilisateur final normal d'atteindre cet objectif.

Si vous proposez également une API permettant aux développeurs de mettre en place leurs propres intégrations, vous devriez probablement traiter cette question dans un autre article(bien que vous puissiez mentionner cette méthode et y faire un lien).

Inclure la documentation du logiciel dans le processus de développement

Lorsqu'on crée une documentation sur un logiciel, il est facile de tomber dans le piège qui consiste à attendre que le projet soit terminé pour le documenter.

Cependant, cela peut rapidement conduire à une dette de documentation, car vous risquez de livrer de nouvelles fonctionnalités ou des changements avant qu'ils n'aient été documentés.

Pour éviter cela, il faut faire de la documentation des logiciels une partie consciente du cycle de développement des logiciels. Si une nouvelle fonctionnalité ou un nouveau produit n'a pas encore été documenté, il n'est pas prêt à être livré, même si le code lui-même est terminé.

En faisant de la documentation une exigence fondamentale du processus de développement de logiciels, vous pouvez vous assurer que tout ce que vous expédiez est accompagné d'une documentation appropriée.

Utiliser un formatage et un style cohérents

Pour aider les utilisateurs à travailler plus efficacement avec la documentation de votre logiciel, il est important d'utiliser un formatage et un style cohérents dans l'ensemble de votre documentation.

L'utilisation de la même mise en forme permet aux lecteurs de savoir comment est structurée la documentation de votre logiciel, ce qui leur permettra d'accéder plus facilement et plus rapidement aux informations dont ils ont besoin.

Pour favoriser cette cohérence, vous pouvez créer un guide de style dédié à la documentation des logiciels.

Votre outil de gestion de la documentation logicielle peut également inclure des fonctions qui vous aideront à obtenir un style cohérent.

Par exemple, le plugin Heroic Knowledge Base comprend des légendes prédéfinies pour mettre en évidence des informations ou des avertissements clés. En les utilisant, vous pouvez garantir une mise en forme cohérente dans l'ensemble de votre documentation.

Faire appel à des experts pour rédiger la documentation technique

Pour la documentation d'un logiciel destinée à l'utilisateur, vous n'aurez peut-être pas besoin d'experts en la matière pour rédiger le contenu.

Toutefois, pour la documentation logicielle plus technique, telle que la documentation sur les API destinée aux développeurs, vous souhaiterez probablement confier la rédaction de ces documents à une personne possédant les connaissances techniques nécessaires.

Il peut s'agir d'un rédacteur technique spécialisé dans le domaine concerné, si votre organisation dispose des ressources nécessaires à l'embauche d'un tel poste. Il peut également s'agir de l'un de vos développeurs.

L'important est que le rédacteur comprenne les aspects techniques de votre logiciel à un niveau suffisamment approfondi pour l'expliquer à d'autres utilisateurs techniques.

Faciliter la découverte du contenu (recherche/filtre)

Au fur et à mesure que votre bibliothèque de documentation s'enrichit, il devient de plus en plus difficile pour les utilisateurs de trouver les articles de documentation qui répondent à leurs besoins.

Pour tenter d'éviter ce problème, vous devez vous efforcer d'améliorer la lisibilité de votre documentation logicielle.

Une première stratégie consiste à diviser votre documentation par type.

Par exemple, vous voudrez généralement séparer la documentation destinée à l'utilisateur final de celle destinée au développeur.

Dans ce cadre, vous pouvez également utiliser des catégories pour diviser davantage les articles. Vous pouvez utiliser des catégories basées sur les fonctionnalités, les cas d'utilisation, les modules complémentaires, etc.

En gardant le même exemple de Gravity Forms, vous pouvez voir que Gravity Forms divise sa documentation pour l'utilisateur final par types de fonctionnalités.

Les suggestions de recherche en direct constituent une autre fonction de découverte utile. Les utilisateurs peuvent commencer à taper une requête pertinente dans le champ de recherche et voir instantanément les articles de la documentation qui correspondent à cette requête.

De nombreux outils de documentation intègrent une fonctionnalité de recherche en direct, notamment Heroic Knowledge Base.

Maintenir la documentation de votre logiciel à jour

Parce que votre logiciel est en constante évolution, votre documentation logicielle sera toujours un travail en cours.

Lorsque des modifications sont apportées à votre logiciel, vous devez rapidement mettre à jour votre documentation pour refléter ces changements.

Dans le cas contraire, votre documentation ne sera pas seulement "inutile", mais elle pourrait même créer de la confusion chez vos utilisateurs.

Pour vous assurer que ces mises à jour ont bien lieu, vous devez désigner des personnes spécifiques chargées de la documentation et du processus de mise à jour. De cette façon, il n'y a aucune ambiguïté quant à la personne responsable de l'exactitude des informations.

Utilisez les commentaires des clients pour améliorer votre documentation

Outre le fait que votre propre équipe travaille à la révision et à la mise à jour de la documentation de votre logiciel, vous devez également tenir compte du retour d'information des clients.

Les clients peuvent fournir des informations précieuses sur l'utilité (ou l'inutilité) d'un certain article de documentation logicielle, ainsi que des détails sur la manière dont vous pourriez l'améliorer.

Pour automatiser le processus de retour d'information des clients, vous devez rechercher un outil de gestion de la documentation qui intègre des fonctions de retour d'information des clients.

Par exemple, le plugin Heroic Knowledge Base permet aux utilisateurs d'évaluer si un article est utile ou non et de fournir des commentaires libres .

Vous pouvez ensuite consulter toutes ces informations à partir de votre tableau de bord afin de repérer rapidement les articles de documentation que vous devez améliorer.

Commencez dès aujourd'hui à documenter vos logiciels

La documentation des logiciels vous aide, vous et vos clients, à travailler plus efficacement et à tirer le meilleur parti de vos logiciels.

Il existe différents types de documentation logicielle, et vous devez donc réfléchir à ceux qui correspondent aux besoins de votre projet.

Vous pouvez avoir une documentation différente pour les équipes internes ou externes, ainsi que pour différents types de clients, tels que les développeurs ou les utilisateurs finaux.

Pour créer une documentation efficace, vous devez suivre les meilleures pratiques décrites dans cet article.

Pour publier cette documentation, vous pouvez utiliser un outil de base de connaissances open-source tel que Heroic KBqui est basé sur le puissant logiciel WordPress.

Vous bénéficiez de la flexibilité et de la propriété d'une plateforme auto-hébergée, avec toutes les caractéristiques et fonctionnalités dont vous avez besoin pour publier une documentation logicielle de haute qualité.