Qu'est-ce que la documentation logicielle ? Types et meilleures pratiques pour commencer

Si vous souhaitez que les développeurs et les utilisateurs finaux tirent le meilleur parti possible de votre logiciel, vous devez créer une documentation logicielle de haute qualité.

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

Dans cet article, nous allons approfondir tout ce que vous devez savoir sur la documentation logicielle, y compris les éléments suivants :

• Qu'est-ce que la documentation logicielle ?
• Les différents types de documentations logicielles (avec exemples)
• Comment publier la documentation de votre logiciel (les meilleurs outils)
• Quelques bonnes pratiques pour créer une documentation logicielle de qualité

Allons creuser !

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.

En règle générale, vous publierez la documentation du logiciel sur votre site Web. Les gens peuvent ensuite y accéder pour en savoir plus sur votre logiciel et son fonctionnement.

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

Les différents types de documentation logicielle

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

La première considération est à 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. Il les 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 pour les développeurs - il s'agit de la documentation logicielle plus technique que vous avez créée pour les développeurs, telle que la documentation de l'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 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.

Par exemple, vous pouvez avoir un ensemble de documentation pour les développeurs pour vos équipes internes afin de vous aider à travailler sur le logiciel et un autre ensemble de documentation destinée 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 du développeur

• Documentation API - montrez aux développeurs comment interagir avec l'API de votre logiciel.
• Lisez-moi - 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 modifications importantes.
• Documentation sur l'architecture - montrez la structure de votre logiciel, y compris éventuellement 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 bogues, les feuilles de route, l'assurance qualité, les protocoles de test, etc.

Pour un véritable exemple de documentation logicielle de documents axés sur les développeurs, vous pouvez consulter la documentation "Développeurs" 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 logicielle pour la documentation utilisateur

• Guide de démarrage - montre aux utilisateurs comment se familiariser rapidement avec votre logiciel.
• Tutoriels pour des cas d'utilisation spécifiques - des tutoriels plus spécifiques pour accomplir des tâches spécifiques.
• Glossaires de termes/manuels de référence – aident les utilisateurs à comprendre les termes et les détails clés.
• FAQ - répondez aux questions fréquemment posées.

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

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

Par rapport à la documentation du 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 une 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 de documentation de logiciel dédié ou d'un certain type de système de gestion des connaissances.

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

Si vous voulez un examen plus approfondi ici, vous voudrez peut-être lire nos guides complets sur les meilleurs outils de documentation et le meilleur logiciel de documentation technique.

Base de connaissances héroïque

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

Avec Heroic Knowledge Base, vous pouvez auto-héberger votre documentation et conserver 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 la base de connaissances héroïque :

• Éditeur de contenu flexible , comprenant des blocs intégrés pour les légendes et d'autres détails de style importants.
• Table des matières automatique afin que les utilisateurs puissent voir rapidement quel contenu est 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 des suggestions en direct, des catégories, etc.
• Système de commentaires des utilisateurs qui permet aux utilisateurs d'évaluer les articles comme utiles ou inutiles et de partager leurs commentaires.
• Analyse de recherche pour que vous puissiez voir ce que les utilisateurs recherchent, ainsi que tous les termes de recherche qui ne renvoient aucun résultat.
• Widget de réponses instantanées pour permettre aux utilisateurs de rechercher et d'accéder à la documentation du logiciel de n'importe où sur votre site.

Parce que Heroic Knowledge Base et WordPress sont à la fois 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 des mots de passe, des comptes d'utilisateurs, des adresses IP, un intranet, etc.

La base de connaissances héroïque commence à seulement 149 $ par an.

Lire la documentation

Read the Docs est un outil de documentation qui vise à 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, cela peut être une autre bonne option à considérer.

Vous pouvez gérer votre contenu et votre historique de révision à 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 versions 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 gratuit si vous avez un projet de logiciel open source.

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 prise en charge des référentiels 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 quelques autres fonctionnalités notables offertes par GitBook :

• Contrôle de version pour garder une trace des révisions et de l'historique des versions.
• Édition en direct par équipe , ce qui est utile si vous avez besoin de faire collaborer plusieurs auteurs sur des articles.
• Organisez les articles en utilisant des "espaces" et des "collections" - chaque espace peut avoir plusieurs collections à l'intérieur.
• Option d'exportation PDF pour que les utilisateurs puissent facilement exporter votre documentation sous forme de téléchargement PDF.

GitBook est gratuit pour les projets à but non lucratif ou 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.

Meilleures 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 sur un logiciel, 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, supposons 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 première publication sur les réseaux sociaux.

Lors de la rédaction de la documentation de votre logiciel, vous voudrez vous concentrer sur la manière la plus simple pour un utilisateur final régulier d'atteindre cet objectif.

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

Inclure la documentation logicielle dans le processus de développement

Lorsque vous créez une 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 fournir de nouvelles fonctionnalités ou des modifications avant qu'elles n'aient été 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 expédié même si le code lui-même est terminé.

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

Utiliser une mise en forme et un style cohérents

Pour aider les gens à travailler plus efficacement avec la documentation de votre logiciel, il est important que vous utilisiez une mise en forme et un style cohérents dans toute votre documentation.

L'utilisation du même formatage permet aux lecteurs d'apprendre comment la documentation de votre logiciel est structurée, ce qui leur facilitera l'accès rapide aux informations dont ils ont besoin.

Pour aider à atteindre cette cohérence, vous souhaiterez peut-être créer un guide de style de documentation logicielle dédié.

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

Par exemple, le plug-in Heroic Knowledge Base comprend des légendes pré-stylées pour mettre en évidence des informations ou des avertissements clés. En les utilisant, vous pouvez garantir une mise en forme cohérente sur l'ensemble de votre documentation.

Utiliser des experts pour rédiger la documentation technique

Pour la documentation logicielle destinée aux utilisateurs, vous n'aurez 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 de l'API axée sur les développeurs, vous souhaiterez probablement désigner une personne possédant les connaissances techniques pertinentes pour rédiger ces documents.

Il peut s'agir d'un rédacteur technique dédié avec une expertise dans le domaine, si votre organisation dispose des ressources nécessaires pour embaucher pour 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 profond pour l'expliquer à d'autres utilisateurs techniques.

Facilitez la découverte de contenu (recherche/filtre)

Au fur et à mesure que votre bibliothèque de documentation grandit, il deviendra plus difficile pour les utilisateurs de trouver les articles de documentation qui répondent à leurs besoins.

Pour essayer d'éviter ce problème, vous devrez vous concentrer sur l'amélioration de la possibilité de découvrir la documentation de votre logiciel.

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

Par exemple, vous souhaiterez généralement séparer votre documentation d'utilisateur final de la documentation du logiciel de développement.

Dans ce cadre, vous pouvez également utiliser des catégories pour diviser davantage les articles. Vous pouvez utiliser des catégories basées sur des fonctionnalités, des cas d'utilisation, des modules complémentaires, etc. - tout ce qui a un sens logique pour votre produit logiciel.

Conformément au même exemple Gravity Forms ci-dessus, vous pouvez voir que Gravity Forms divise sa documentation d'utilisateur final par types de fonctionnalités.

Une autre fonctionnalité de découverte utile est les suggestions de recherche en direct. Les utilisateurs peuvent commencer à saisir une requête pertinente dans le champ de recherche et voir instantanément les articles de documentation correspondant à cette requête.

De nombreux outils de documentation incluent une fonctionnalité de recherche en direct intégrée, y compris la base de connaissances héroïque.

Gardez la documentation de votre logiciel à jour

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

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

Sinon, votre documentation ne sera pas simplement "inutile", mais elle pourrait en fait créer de la confusion chez vos utilisateurs.

Pour vous assurer que ces mises à jour se produisent, vous souhaiterez affecter des personnes spécifiques à la propriété de la documentation et du processus de mise à jour. De cette façon, il n'y a pas d'ambiguïté quant à savoir qui est responsable de l'exactitude de tout.

Utilisez les commentaires des clients pour améliorer votre documentation

En plus de faire travailler votre propre équipe sur la révision et la mise à jour de la documentation de votre logiciel, vous voudrez également prendre en compte les commentaires des clients.

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

Pour automatiser le processus de rétroaction des clients, vous voudrez rechercher un outil de gestion de la documentation qui inclut des fonctionnalités intégrées pour les commentaires des clients.

Par exemple, le plugin Heroic Knowledge Base permet aux utilisateurs d'évaluer un article comme utile ou inutile et également de fournir éventuellement des commentaires sous forme libre.

Vous pouvez ensuite visualiser 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, vous et vos clients, à travailler plus efficacement et à tirer le meilleur parti de votre logiciel.

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

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 et les utilisateurs finaux.

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

Pour publier cette documentation, vous pouvez utiliser un outil open source comme Heroic Knowledge Base, qui est basé sur le puissant logiciel WordPress.

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

Si vous voulez en savoir plus, cliquez ici pour accéder à la base de connaissances héroïque.