Qu'est-ce que la documentation logicielle ? 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 logicielle réellement, et comment pouvez-vous en créer pour votre projet ?

Dans cet article, nous allons explorer tout ce que vous devez savoir sur la documentation logicielle, y compris les points suivants :

Allons-y !

Qu'est-ce que la documentation logicielle ?

La documentation logicielle 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.

Généralement, vous publierez la documentation logicielle sur votre site Web. Les gens pourront alors y accéder pour en savoir plus sur votre logiciel et son fonctionnement.

Dans cette définition générale de la documentation logicielle, il existe différents types de documentation logicielle. Discutons-en ensuite.

Les différents types de documentation logicielle

Vous pouvez diviser grossièrement les différents types de documentation logicielle en quelques grandes catégories.

La première considération est le type de personne à qui 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 l'aide à comprendre comment utiliser votre logiciel du point de vue d'un utilisateur régulier, qui peut ou non avoir des connaissances techniques particulières.
• Documentation développeur – il s'agit d'une documentation logicielle plus technique que vous avez créée pour les développeurs, telle que la documentation d'API.

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

• Documentation logicielle externe – il s'agit d'une documentation publique que vous avez créée pour aider vos utilisateurs.
• Documentation logicielle interne – 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 pourriez avoir un ensemble de documentation pour les développeurs destiné à vos équipes internes pour les aider à travailler sur le logiciel, et un autre ensemble de documentation pour les développeurs destiné au public pour les développeurs externes.

Décomposons ces types de documentation logicielle un peu plus en détail...

Exemples de documentation logicielle pour la documentation des développeurs

• Documentation API – montrez aux développeurs comment interagir avec l'API de votre logiciel.
• Readme – présentez votre logiciel et expliquez ce qu'il fait – généralement la première chose que les gens lisent.
• Notes de version – documentez les nouvelles versions de votre logiciel, y compris les changements importants.
• Documentation d'architecture – montrez la structure de votre logiciel, y compris potentiellement des diagrammes.
• Documentation du modèle de données – documentez 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 – documentez les processus clés tels que les rapports de bugs, les feuilles de route, l'assurance qualité, les protocoles de test, etc.

Pour un exemple concret de documentation logicielle axée sur les développeurs, vous pouvez consulter la documentation « Développeurs » de Gravity Forms qui couvre divers sujets tels que :

• Hooks 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 logicielle pour la documentation utilisateur

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

Pour un exemple concret de ce à quoi pourrait ressembler une documentation logicielle plus axée sur l'utilisateur, vous pouvez vous tourner vers le même exemple de Gravity Forms ci-dessus.

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 d'accomplir des tâches en utilisant l'interface logicielle, ainsi que des glossaires et des explications des fonctionnalités clés.

Comparé à la documentation logicielle pour développeurs, vous verrez plus de captures d'écran et d'explications en langage clair, et beaucoup moins de blocs de code.

Comment publier la documentation logicielle : trois meilleurs outils de documentation logicielle

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

Dans cette section, nous passerons rapidement en revue certains des meilleurs outils de documentation logicielle. Ensuite, dans la section suivante, nous aborderons quelques bonnes pratiques pour créer une documentation de qualité.

Si vous souhaitez un aperçu plus approfondi, vous pourriez lire nos guides complets sur les meilleurs outils de documentation et les meilleurs logiciels de documentation technique.

Base de connaissances Heroic

Heroic Knowledge Base est un plugin de documentation et de base de connaissances pour le logiciel populaire open-source WordPress.

Avec Heroic Knowledge Base, vous pouvez auto-héberger votre documentation et conserver le 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 principales que vous obtenez avec Heroic Knowledge Base :

• Éditeur de contenu flexible, y compris des blocs intégrés pour les encadrés et autres détails de style importants.
• Table des matières automatique afin que les utilisateurs puissent voir rapidement le contenu couvert dans un article de documentation et 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, y compris la recherche Ajax en temps réel avec suggestions instantanées, catégories, et plus encore.
• Système de retour d'information des utilisateurs qui permet aux gens d'évaluer les articles comme utiles ou non utiles et de partager leurs commentaires.
• Analytique de recherche pour que vous puissiez voir ce que les utilisateurs recherchent, ainsi que les termes de recherche qui ne donnent aucun résultat.
• Widget de réponses instantanées pour permettre aux utilisateurs de rechercher et d'accéder à la documentation logicielle depuis n'importe où sur votre site.

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

Vous pouvez le rendre public ou restreindre l'accès à votre documentation avec diverses tactiques telles que les mots de passe, les comptes d'utilisateurs, les adresses IP, un intranet, et plus encore.

Heroic Knowledge Base commence à seulement 67 $ par an.

Read the Docs

Read the Docs est un outil de documentation axé sur l'aide à la création de documentation pour développeurs.

Si vous vous concentrez spécifiquement sur la création de documentation technique pour développeurs, cela peut être une autre bonne option à considérer.

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

Voici quelques-unes des autres fonctionnalités notables de Read the Docs :

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

Read the Docs est un logiciel de documentation open-source gratuit.

Pour les produits logiciels commerciaux, il existe un service payant Read the Docs for Business qui commence à 50 $ par mois.

GitBook

GitBook est un autre outil de documentation logicielle technique qui vous permet de gérer votre documentation à l'aide de Git, avec la prise en charge des dépôts GitHub et GitLab.

Ou, 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 que GitBook offre :

• Contrôle de version pour suivre les révisions et l'historique des versions.
• Édition d'équipe en direct, ce qui est utile si vous avez besoin que plusieurs auteurs collaborent sur des articles.
• Organisez les articles à l'aide d'« espaces » et de « collections » – chaque espace peut contenir plusieurs collections à l'intérieur.
• **Exportation PDF** option pour que les utilisateurs puissent facilement exporter votre documentation en téléchargement 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 par mois, avec un minimum de 5 utilisateurs. Cela signifie que le tarif mensuel le plus bas est de 40 $ par mois.

Bonnes pratiques pour la création de documentation logicielle

Pour finir, examinons quelques bonnes pratiques en matière de documentation logicielle pour vous aider à créer une documentation efficace.

Pensez aux objectifs et aux besoins des utilisateurs

Lorsque vous rédigez un article de documentation logicielle, il est important de commencer par répondre à quelques questions de base :

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

Connaître les réponses à ces questions vous aidera à comprendre quel contenu couvrir et comment structurer l'article de la manière la plus optimale.

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

Lorsque vous rédigez votre documentation logicielle, vous voudrez vous concentrer sur la manière la plus simple pour un utilisateur final ordinaire d'atteindre cet objectif.

Si vous proposez également une API pour permettre aux développeurs de mettre en place leurs propres intégrations, vous voudrez probablement couvrir cela dans un article différent (bien que vous puissiez mentionner et lier cette méthode).

Inclure la documentation logicielle dans le processus de développement

Lorsque vous créez de la documentation logicielle, il est facile de tomber dans le piège d'attendre qu'un projet soit terminé pour le documenter.

Cependant, cela peut rapidement entraîner une dette de documentation car vous pourriez livrer de nouvelles fonctionnalités ou des modifications avant qu'elles ne soient documentées.

Pour éviter cela, faites de la documentation logicielle une partie consciente du cycle de développement logiciel. 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 logiciel, vous pouvez vous assurer que tout ce que vous livrez est accompagné d'une documentation appropriée.

Utiliser un formatage et un style cohérents

Pour aider les gens à travailler plus efficacement avec votre documentation logicielle, il est important que vous utilisiez un formatage et un style cohérents dans toute votre documentation.

L'utilisation du même formatage permet aux lecteurs d'apprendre comment votre documentation logicielle est structurée, ce qui leur permettra d'accéder plus facilement aux informations dont ils ont besoin.

Pour vous aider à atteindre cette cohérence, vous pourriez vouloir créer un guide de style de documentation dédié.

Votre outil de gestion de documentation logicielle peut également inclure des fonctionnalités pour vous aider à obtenir un style cohérent.

Par exemple, le plugin Heroic Knowledge Base inclut des encarts pré-stylisés pour mettre en évidence les informations clés ou les avertissements. En les utilisant, vous pouvez assurer un formatage cohérent dans toute votre documentation.

Utiliser des experts pour rédiger la documentation technique

Pour la documentation logicielle destinée aux utilisateurs, vous n'avez peut-être pas besoin d'experts en la matière pour rédiger le contenu.

Cependant, pour une documentation logicielle plus technique, telle que la documentation API axée sur les développeurs, vous voudrez probablement confier la rédaction de ces documents à une personne possédant les connaissances techniques pertinentes.

Il pourrait s'agir d'un rédacteur technique dédié avec une expertise dans le domaine, si votre organisation a les ressources pour embaucher à ce poste. Ou, il pourrait 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.

Facilitez la découverte de contenu (Recherche/Filtre)

À mesure que votre bibliothèque de documentation s'agrandit, il deviendra plus difficile pour les utilisateurs de trouver les articles de documentation qui répondent à leurs besoins.

Pour tenter d'éviter ce problème, vous voudrez vous concentrer sur l'amélioration de la découvrabilité de votre documentation logicielle.

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

Par exemple, vous voudrez généralement séparer votre documentation utilisateur de la documentation logicielle pour développeurs.

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. – tout ce qui a un sens logique pour votre produit logiciel.

En gardant le même exemple de Gravity Forms ci-dessus, vous pouvez voir que Gravity Forms divise sa documentation utilisateur par types de fonctionnalités.

Une autre fonctionnalité de découvrabilité utile est les suggestions de recherche en direct. Les utilisateurs peuvent commencer à taper une requête pertinente dans la boîte de recherche et voir instantanément les articles de documentation qui correspondent à cette requête.

De nombreux outils de documentation incluent une fonctionnalité de recherche en direct intégrée, notamment Heroic Knowledge Base.

Gardez la documentation de votre logiciel à jour

Parce que votre logiciel évolue constamment, la documentation de votre logiciel sera toujours en cours de développement.

Au fur et à mesure que des changements interviennent dans votre logiciel, vous devrez rapidement mettre à jour votre documentation pour refléter ces changements.

Sinon, votre documentation ne sera pas seulement « peu utile », mais elle pourrait en réalité créer de la confusion chez vos utilisateurs.

Pour vous assurer que ces mises à jour ont lieu, vous voudrez attribuer des personnes spécifiques pour gérer la documentation et le processus de mise à jour. Ainsi, il n'y aura aucune ambiguïté quant à la responsabilité de maintenir l'exactitude de tout.

Utilisez les retours clients pour améliorer votre documentation

En plus de faire travailler votre propre équipe à la révision et à la mise à jour de la documentation de votre logiciel, vous voudrez également tenir compte des retours clients.

Les clients peuvent fournir des informations précieuses sur l'utilité (ou le manque d'utilité) d'un article de documentation logicielle donné, ainsi que des détails sur la façon dont vous pourriez l'améliorer.

Pour automatiser le processus de retour client, vous voudrez rechercher un outil de gestion de documentation qui inclut des fonctionnalités intégrées pour les retours clients.

Par exemple, le plugin Heroic Knowledge Base permet aux utilisateurs de noter un article comme utile ou inutile et de fournir également facultativement des commentaires libres.

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

Commencez à documenter votre logiciel dès aujourd'hui

La documentation logicielle vous aide, ainsi que vos clients, à travailler plus efficacement et à tirer le meilleur parti de votre logiciel.

Il existe différents types de documentation logicielle, vous voudrez donc réfléchir aux types qui correspondent aux besoins de votre projet logiciel.

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

Pour créer une documentation efficace, vous voudrez suivre les meilleures pratiques de cet article.

Pour publier cette documentation, vous pouvez utiliser des outils de base de connaissances open-source comme Heroic KB, qui est basé sur le puissant logiciel WordPress.

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