6 meilleurs exemples de documentation logicielle et meilleures pratiques

Vous voulez connaître le succès derrière les bons produits logiciels florissants?

C'est leur documentation.

Les bonnes entreprises investissent beaucoup dans leur documentation logicielle. En fait, la première chose qu'ils font est de créer une documentation qui inclut le but, la portée, la portée, le travail et les références de l'industrie du logiciel.

Cela permet aux parties prenantes de jeter un aperçu du coût de développement des logiciels, du calendrier, de l'angle de marketing et des stratégies, de l'écart de fonctionnalité et des caractéristiques clés sur lesquelles se concentrer.

Non seulement, il aide au développement, mais la documentation logicielle est l'une des méthodes les plus couramment utilisées pour former de nouveaux employés, intégrer de nouveaux clients et fournir un soutien.

Nous avons également créé plusieurs logiciels et leur documentation, à partir de cela, nous pouvons vous guider avec votre documentation logicielle .

Alors, commençons!

Nous testons et recherchons rigoureusement tous les produits que nous recommandons via Herothemes. Notre processus d'examen. Nous pouvons également gagner une commission si vous effectuez un achat via nos liens.

Qu'est-ce que la documentation logicielle?

La documentation logicielle est tout matériel écrit ou vidéo qui facilite le développement de logiciels, les processus de développement d'enregistrement et les progrès, explique comment fonctionne une application logicielle, guide les utilisateurs utilisant efficacement le logiciel et sert de matériel de support client.

Types de documentation logicielle

Un projet logiciel peut prendre quelques jours à quelques années. Donc, avant de commencer avec n'importe quel logiciel d'entreprise, il est important de comprendre dans quoi vous plongez.

En conséquence, la documentation logicielle couvre une vaste gamme de documentation. De la planification des étapes à se conformer aux lois.

Certains des documents produits dans le cycle de vie du développement logiciel, Source - CDS.Cern.ch

Cela vous aidera à avoir une idée générale de la façon de démarrer la documentation de votre logiciel et les choses à couvrir.

1. Documentation du projet

La documentation du projet est créée pendant les étapes initiales de la création de logiciels et maintenue tout au long de son cycle de vie.

Comme il donne aux oiseaux une vue sur le processus de développement des logiciels, cela aide grandement à la prise de décision.

Il couvre la recherche, les tests, les idées, les exemples, l'allocation des ressources, les détails des réunions, les progrès du travail, les jalons et les objectifs futurs.

2. Documentation des exigences et de la conception

Exigences et documentation de conception Travaillent les deux au corps à corps. C'est comme créer une esquisse approximative de votre logiciel avant de commencer à le coder.

Il comprend des composants clés tels que:

• Aperçu du système
• Buts et objectifs de haut niveau
• Exigences fonctionnelles
• Critères d'acceptation
• Architecture du système
• Pile technologique

Bien que la documentation des exigences se concentre sur ce que le système doit faire, la documentation de conception se concentre sur la façon dont le système sera construit.

Meilleures pratiques: il est préférable de répertorier toutes vos exigences du logiciel et de les diviser en plusieurs étapes. Cela vous aidera à concevoir de meilleurs logiciels dès le début.

De nombreux logiciels sont repensés (par exemple, réécrits dans une langue différente ou rétructuré) simplement parce qu'il n'a pas été conçu correctement en premier lieu.

3. Documentation technique

La documentation technique couvre la façon dont les systèmes logiciels sont construits, exploités et entretenus.

Dans la documentation logicielle, vous devez créer une documentation technique pour expliquer:

• Comment le code fonctionne
• API (interface de programmation d'application)
• Schéma de base de données (tableaux, relations et flux de données)
• Comment mettre à niveau les dépendances logicielles
• Guides de dépannage

Nous avons un guide complet pour créer et rédiger une documentation technique, le consulter!

4. Documentation utilisateur

La documentation utilisateur aide les utilisateurs finaux (clients) à utiliser efficacement votre logiciel.

Il comprend:

• Manuels d'utilisateurs : créé pour les utilisateurs finaux. Par exemple, comment les utilisateurs peuvent utiliser une fonctionnalité particulière de votre produit.
• Matériel de formation: il contient diverses ressources de formation pour les utilisateurs finaux. Par exemple, des guides de configuration, des vidéos ou des cours.

La documentation utilisateur est un peu différente d'une documentation technique, nous avons quelques guides qui vous aideront à en savoir plus:

• 5 meilleurs exemples de documentation utilisateur (bon et mauvais + conseils)
• Comment créer un manuel d'utilisation: de zéro au héros (guide complet)

5. Test de documentation

Documentation ou directives de test spécialement créées pour les équipes d'AQ (assurance qualité). Pour garantir que la qualité des logiciels répond aux normes de marché ou répond aux demandes des parties prenantes.

Il comprend:

• Plan de test et cas de test
• Listes de contrôle à suivre lors du test d'une fonction logicielle
• Directives de qualité du code
• Tests automatisés

6. Documentation de la maintenance / de la sécurité

Ce type de documentation aide les développeurs et les équipes à maintenir, mettre à jour, déboguer et dépanner le logiciel.

Il comprend:

• Mettre à jour les directives ou les listes de contrôle
• Guides pour mettre à jour les dépendances logicielles
• Contrôles d'accès
• Plan d'incident
• Notes de libération

7. Documentation juridique et conformité

Documentation juridique et conformité pour s'assurer que le logiciel suit les normes légales, réglementaires et de l'industrie.

Documents juridiques tels que:

• Contrat de licence de l'utilisateur final (CLU)
• Conditions d'utilisation (TOS)
• Politique de confidentialité
• Licences logicielles et informations d'utilisation

Documents de conformité tels que:

• Protection des données et conformité à la confidentialité, qui comprend des réglementations telles que le RGPD, le CCPA ou le HIPAA.
• Conformité à la sécurité
• Conformité à l'accessibilité
• Règlements spécifiques à l'industrie

Explorer : Qu'est-ce que la documentation logicielle?

6 meilleurs exemples de documentation logicielle à apprendre

1. WordPress

Il y a de fortes chances que vous ayez déjà utilisé WordPress auparavant, donc cela pourrait être le meilleur exemple de documentation logicielle à apprendre.

WordPress est utilisé sur 43% de tous les sites Web sur le Web. Donc, sa documentation doit être l'une des meilleures pour servir des millions de personnes du monde entier.

Cela inclut les développeurs, les concepteurs, les blogueurs, les écrivains ou toute personne qui souhaite créer un site Web.

La documentation principale de WordPress est divisée en trois sections différentes :

1. Apprendre WordPress: comprend des guides sous la forme de cours approfondis, de vidéos et de tutoriels écrits. Ciblé vers les utilisateurs débutants, intermédiaires et avancés.
2. Documentation principale: destiné aux utilisateurs normaux. Pour fournir un aperçu des fonctionnalités WordPress, sous la forme de courts tutoriels écrits simples.
3. Ressources du développeur: destiné aux développeurs qui créent des thèmes WordPress, des plugins ou souhaitent étendre WordPress avec un codage personnalisé. Il comprend des guides de départ, une documentation de l'API et des exemples de codage.

Dans l'ensemble, cela crée un centre de ressources parfait pour tous ceux qui souhaitent créer un site Web ou commencer avec WordPress. Il est facile de naviguer, de rechercher convivial, de profondeur, plein d'exemples et très utile.

Choses à apprendre de la documentation du logiciel WordPress:

• Ils connaissent leur public , en conséquence, vous pouvez voir plusieurs sections de documentation et guides créés en fonction du niveau de connaissances ou de l'expertise des utilisateurs .
• Mises à jour continues . La documentation logicielle n'est pas une chose unique, les fonctionnalités logicielles, l'interface utilisateur ou les fonctionnalités peuvent changer avec le temps. La même chose s'est produite avec WordPress (du thème classique à un thème de bloc et de l'ajout de Gutenberg) et ils se sont assurés de mettre à jour leur documentation à chaque mise à jour.
• Forums de support . Outre les didacticiels et guides pré-même, WordPress comprend également un forum d'assistance pour chaque plugin et thème. Ceci est très utile au cas où les utilisateurs auraient du mal à résoudre les problèmes par eux-mêmes.
• SEO (recherche de moteur convivial) . Au cours de ma carrière de plus de 9 ans en tant qu'utilisateur WordPress , j'ai rarement visité ou parcouru la documentation WordPress directement. Tout ce que j'ai fait, c'est rechercher sur Google et j'ai trouvé la solution à mes requêtes. Les documents WordPress et les pages de support générés par les utilisateurs sont facilement indexés sur Google (ou d'autres moteurs de recherche) qui vous permettent de les trouver facilement.
• FAQ . La plupart du temps, les FAQ sont manquées dans la documentation. Mais WordPress n'a pas manqué. Les FAQ fournissent des informations instantanées ou une solution et sont faciles à parcourir.
• Système de rétroaction . Vous pouvez fournir des commentaires sur chaque guide, ce qui est une fonctionnalité utile pour trouver des guides surpassés et inutiles.

Que ne l'aimez pas dans la documentation WordPress:

• Pas de documentation multilingue . Bien que vous puissiez facilement trouver des guides tiers WordPress dans votre langue. Mais je souhaite que WordPress ait créé des tutoriels pour les langues populaires.

2. Base de connaissances Herothemes

Notre propre documentation logicielle.

Ce n'est pas le meilleur exemple, mais étant donné que la plupart d'entre vous ont une situation similaire à la nôtre:

• Aucune idée du départ
• Petit budget

Cela peut être un bon exemple à apprendre.

Herothemes fournit des plugins d'assistance client, y compris une base de connaissances héroïque qui permet aux utilisateurs de créer une base de connaissances ou des sites Web de documentation sans aucune connaissance de codage, à usage public et interne.

Choses à apprendre de l'exemple de documentation Herothemes:

• Créer uniquement la documentation nécessaire et l'améliorer. Herothemes a très peu de guides, étant donné que la plupart des clients ciblés sont du niveau intermédiaire (développeurs, utilisateurs de WordPress) et que le logiciel est très simple et simple à utiliser.
• Table des matières (COT) . Étant donné que certains de ces guides contiennent des procédures pas à pas complètes, le COT aide à trouver les informations nécessaires.
• Captures d'écran . Comme la plupart d'entre nous ne peuvent pas épargner un bon budget pour la documentation (en particulier l'attribution d'un concepteur pour créer des visuels de qualité) dès le début, l'ajout de captures d'écran est bien mieux que d'ajouter rien. Cependant, les visuels créés par des concepteurs donnent vraiment une sensation premium.
• Documentation pour prendre en charge le suivi des billets .

C'est l'une des fonctionnalités héroïques de KB Analytics pour suivre les billets de support provenant de la documentation. Très utile pour trouver un contenu inutile et obsolète.

• FAQ . Les utilisateurs demandent beaucoup de questions fréquemment posées telles que la politique de remboursement ou les futures mises à niveau, leur répondre via la documentation aide les utilisateurs à les trouver facilement avec une barre de recherche et une assistante d'aide à l'IA.
• AIDE AIDE AI . Semblable aux barres de recherche, AI Help Assistant aide les utilisateurs à trouver facilement des réponses à leurs requêtes. Il est formé sur le contenu de la documentation, donc les réponses sont pertinentes et utiles.

Que ne l'aimez pas dans la documentation Herothemes:

Étant donné que Herothemes propose plusieurs solutions logicielles, le regroupement de contenu de documentation est un peu un gâchis .

Nous avons des guides pour vous aider à créer un site Web de documentation avec WordPress:

• Comment créer une base de connaissances WordPress (guide étape par étape)
• Comment créer une documentation interne

3. Documentation du portefeuille de logiciels BARN2

Barn2 vend plusieurs produits logiciels basés sur WordPress et WooCommerce qui sont utilisés sur plus de 90 000 sites Web.

Servir plusieurs documents logiciels à partir d'un seul portail peut être difficile, mais Barn2 le fait à merveille.

Vous devriez certainement examiner l'exemple de Barn2 si vous avez plusieurs produits.

Choses à apprendre de l'exemple de documentation BARN2:

Barn2 a très soigneusement conçu sa page de soutien. Qui peut être vu avec sa fonctionnalité globale et son utilité.

Lorsque vous visitez leur page d'assistance, vous trouverez une barre de recherche proéminente avec une option pour sélectionner un produit spécifique .

Les questions fréquemment posées liées aux préventes, aux licences, aux mises à jour et aux problèmes techniques. C'est très engageant pour interagir et il fournit également des réponses rapides .

Lorsque la recherche ne fournit pas de résultats, il montre un moyen d'atteindre le soutien humain.

Parler de la documentation logicielle principale:

• Vous trouverez tous les guides importants en haut et les guides sont divisés en différentes sections pour une navigation facile.
• Comprend des tutoriels écrits et vidéo.
• Le support humain est facilement accessible avec la barre latérale CTA.
• Blocs / conceptions personnalisés pour les notes, les conseils, les messages d'avertissement et les extraits de code pour améliorer la capacité de numérisation.

Que ne l'aimez pas dans la documentation de Barn2:

• Pas de système de rétroaction . Bien qu'ils fournissent un accès direct au support humain, il n'y a aucun moyen pour eux de recueillir des commentaires en temps réel des utilisateurs. Ce qui peut entraîner des informations et des tutoriels obsolètes.

Barn2 utilise également une base de connaissances héroïque pour créer leur documentation logicielle.

4. Guide de l'utilisateur de l'iPhone

Il y a beaucoup de choses à aimer et à ne pas aimer dans la documentation utilisateur de l'iPhone (guides logiciels iOS).

C'est une documentation logicielle qui a l'air fantaisiste avec des instructions faciles à suivre, quelque chose comme celui-ci que vous pouvez attendre d'Apple.

Choses à apprendre de l'exemple de documentation de l'iPhone:

La documentation des iPhones est magnifique .

• Une seule mise en page de colonne
• Beaucoup d'espace blanc
• Petit paragraphe et contenu
• Beaux visuels
• Bonne utilisation des titres, des listes et des séparateurs

La plupart des objectifs de leur documentation visent à créer des guides aussi étonnants et utiles visuellement.

Lorsque vous trouvez le guide pertinent, il faut moins d'une minute pour le parcourir et comprendre quoi faire.

La documentation de l'iPhone est spécialement créée de cette façon, afin que tout le monde puisse facilement le comprendre.

Si vous cherchez à créer une documentation de logiciels de produits, je recommande fortement de créer des guides utilisateur similaires à l'iPhone si vous avez un budget à épargner pour la documentation.

En plus d'embellir leur documentation, Apple n'a pas oublié d' utiliser correctement le référencement . Être précis:

• Titre et structure de cap
• Intercluse dans une forme de TOC, postes connexes, navigation précédente et prochaine

Le système de rétroaction du guide est génial . Vous cliquez sur oui ou non, et si nécessaire, donnez également des commentaires.

Le système de rétroaction ne semble pas si cool, mais lorsque vous avez des millions d'utilisateurs qui vous donnent des commentaires, un suivi simple ou non est vraiment utile pour vérifier les performances des guides (vous ne pouvez tout simplement pas lire tous ces commentaires, pouvez-vous?) .

Apple fournit également des guides basés sur les versions logicielles (dans ce cas, la version iOS).

Que ne l'aimez pas dans la documentation de l'iPhone:

J'ai beaucoup salué la documentation de l'iPhone ci-dessus, mais il y a aussi des trucs ennuyeux.

En particulier la partie de navigation.

• La table des matières n'est pas utile, car elle inclut tous les liens de guide.
• L'icône de recherche est trop petite pour être remarquée.

5. Document de conception logicielle (exemple interne)

La documentation logicielle commence à partir de l'idée même de créer un logiciel.

Par exemple, votre documentation logicielle initiale pourrait inclure:

• Quels sont les besoins du logiciel
• Portée
• Comment ça fonctionnera
• Références

Le fait d'avoir des informations détaillées aidera à éviter de nombreuses réunions futures, à former de nouveaux employés et à créer des directives concrètes.

Vous pouvez apprendre beaucoup du document de conception du logiciel des conseillers sur road trip.

Il décrit toutes les exigences nécessaires pour commencer à créer des logiciels (dans ce cas, une application Web) ou pour aider les nouveaux employés à comprendre les exigences du logiciel.

De plus, vous pouvez toujours l'améliorer pendant le développement de logiciels.

Choses à apprendre de cet exemple:

• Comprend des informations de base mais importantes telles que l'objectif, la portée et les définitions qui crée des directives concrètes.
• Utilisation de diagrammes et de graphiques visuels pour aider les développeurs à mieux comprendre les exigences. Par exemple: décrire les connexions ou le flux de la fonctionnalité avec des diagrammes.

6. Documentation Google

Qui ne connaît pas Google? Nous utilisons chaque jour leur logiciel haut de gamme, comme Chrome, Gmail, Google Maps, Google Drive ou YouTube.

Ils sont disponibles pour les appareils informatiques et mobiles. Différents systèmes d'exploitation, dispositifs, résolutions et paramètres.

Dans une telle situation, ce doit être un cauchemar de créer quelque chose de bien sans gâchis. Et Google fait un très bon travail avec leur documentation .

Choses à apprendre de la documentation logicielle de Google:

• Excellente utilisation des onglets et de l'accordéon pour simplifier les clusters de contenu.

Si vous créez un logiciel pour plusieurs appareils, c'est ainsi que vous pouvez éviter de créer plusieurs documents.

• Système de rétroaction génial. Semblable à certains des exemples ci-dessus, Google comprend également un système de rétroaction oui / non qui recueille également les commentaires des utilisateurs.

Mais Google va un pas plus loin ici. Ils ont un système en place qui recueille des commentaires en fonction de sections spécifiques . Ce qui est très intuitif et pratique.

• Contenu rapide . Allez-y, cliquez dessus, téléchargez, installez et boom. C'est à quel point les tutoriels de la documentation Google sont rapides.
• Bars supérieures pour accéder rapidement à la recherche, au centre d'aide, à la communauté et à la page de produit.
• Documentation disponible en plusieurs langues .

Que ne l'aimez pas dans la documentation de Google:

J'ai essayé de trouver beaucoup de choses à me plaindre ici, mais à la fin je ne pouvais pas le faire. Google a certainement une bonne documentation logicielle.

Réflexions finales

Nous avons couvert de nombreux exemples différents dans ce guide d'exemples de documentation logicielle et partagé notre expérience personnelle également.

Voici quelques derniers mots:

1. Lorsque vous commencez par la création de logiciels , créez des guides internes qui décrivent les critères de l'objectif, de la portée, des fonctionnalités et de la publication logiciels.
2. Créez votre portefeuille de documentation lorsque vous développez un logiciel . Par exemple, la documentation de l'API et la documentation technique.
3. Avant de lancer le logiciel , créez une documentation utilisateur qui comprend des guides de configuration, des cas d'utilisation, une vue d'ensemble des fonctionnalités et des questions fréquemment posées.
4. Après le lancement , créez des tutoriels pour résoudre les problèmes d'utilisateurs les plus courants et améliorer votre ancienne documentation.

La documentation n'est pas une blague; Il peut vous épargner des horribles processus de réaménagement des logiciels ou de refonte. Je peux vous aider à offrir une meilleure expérience client et à retenir les clients.

Si vous recherchez une solution de documentation logicielle , la base de connaissances héroïque a tout à offrir dont nous avons discuté dans ce guide.

Essayez-le!