Aller au contenu
For Sellers

Une documentation qui réduit les tickets de support pour les produits de code

Comment rédiger une documentation logicielle pour les clients qui achètent votre code source : les six documents dont chaque produit a besoin, un modèle de guide d’installation, des entrées de dépannage construites autour de vrais messages d’erreur, et une boucle mensuelle qui transforme les tickets en documentation.

• Nov 17, 2026 • 14 min de lecture
Une documentation qui réduit les tickets de support pour les produits de code

La plupart des tickets de support pour les produits de code source ne sont pas des bugs. Ce sont des problèmes d’installation, des questions de configuration et des demandes du type « comment modifier X » auxquelles quelques pages bien placées auraient répondu. Une bonne documentation logicielle destinée aux clients s’organise autour de ces questions : ce dont l’acheteur a besoin pour installer l’application, la configurer, l’utiliser, la personnaliser, la mettre à jour et la réparer quand quelque chose ne va pas.

La documentation influence aussi la décision d’achat elle-même. C’est l’un des signaux de confiance décrits dans notre guide sur comment vendre le code source de votre application web ou SaaS, et les relecteurs d’AppTrovo vérifient la présence d’instructions d’installation et d’utilisation claires avant qu’un produit soit mis en ligne. Ce guide vous montre quoi rédiger, dans quel ordre, et comment garder le tout exact avec presque aucun effort supplémentaire.

L’objectif n’est pas d’avoir plus de pages. C’est d’avoir moins de tickets par vente, ce qui rend une licence unique rentable dans la durée.

De quels documents un produit de code a-t-il besoin ?

Les acheteurs de code source arrivent avec des objectifs différents à des moments différents. Séparez votre documentation par objectif pour que chaque lecteur trouve rapidement sa réponse. Le cadre Diátaxis est un modèle reconnu pour cette répartition entre tutoriels, guides pratiques, référence et explications. Pour une application web vendable, six documents couvrent presque tout :

DocumentQuestion du lecteurÉvite des tickets comme
README / Démarrage rapideQu’est-ce que c’est et comment le faire fonctionner ?« Par où commencer ? », « Quel fichier dois-je téléverser ? »
Guide d’installationComment l’installer sur mon serveur, étape par étape ?« Page blanche après le téléversement », « Erreur de connexion à la base de données »
Référence de configurationÀ quoi sert chaque paramètre et chaque variable d’environnement ?« Les e-mails ne partent pas », « Comment changer la devise ? »
Guide utilisateurComment effectuer une tâche dans l’application ?« Comment ajouter un membre du personnel ? », « Où sont les rapports ? »
Guide de personnalisationComment modifier le code en toute sécurité ?« Comment changer le logo ? », « Comment ajouter un champ ? »
Dépannage et notes de mise à jourQuelque chose ne fonctionne plus, ou je veux la nouvelle version« Erreur 500 après la mise à jour », « Les tâches en file d’attente ne s’exécutent pas »

Livrez la documentation dans le téléchargement (un dossier docs/ ou un fichier HTML) et publiez le même contenu en ligne. Les acheteurs qui recherchent un message d’erreur trouveront une page publique ; ceux dont le serveur n’a pas d’accès à Internet pourront toujours lire la copie locale.

Commencez par un README écrit pour les acheteurs

Le README de votre dépôt a probablement été écrit pour vous-même. Le README d’un acheteur répond à d’autres questions dès le premier écran :

  1. Ce que c’est, en une phrase.
  2. Prérequis : version du langage, extensions, base de données, cron, file d’attente, éventuels services tiers payants.
  3. Le contenu du ZIP : quel dossier téléverser, lequel contient la documentation, lequel est facultatif (fichiers de design, données d’exemple).
  4. Le chemin le plus rapide vers une application fonctionnelle : cinq à dix lignes, avec un lien vers le guide d’installation complet.
  5. Les identifiants par défaut créés par l’installateur, avec un rappel de les changer.
  6. Où obtenir de l’aide : lien vers la documentation, comment ouvrir un ticket de support et ce qu’il faut y inclure.
  7. Version et lien vers le journal des modifications.

Modèle de guide d’installation

Le guide d’installation évite plus de tickets que tout le reste réuni. Rédigez-le en installant votre produit sur un serveur vierge tout en prenant des notes, jamais de mémoire. Utilisez cette structure :

  1. Avant de commencer. Une liste de contrôle que l’acheteur peut cocher : accès au serveur, version de PHP ou de l’environnement d’exécution, extensions requises, une base de données et un utilisateur disposant de tous les privilèges sur celle-ci, un domaine pointant vers le serveur, un certificat SSL, la possibilité de configurer une tâche cron.
  2. Téléversez les fichiers. Indiquez précisément quel dossier va où, et quel dossier doit être la racine web (pour une application Laravel, public/). Ajoutez une note pour l’hébergement mutualisé si la racine web ne peut pas être modifiée.
  3. Installez les dépendances si elles ne sont pas incluses, avec les commandes exactes, comme composer install --no-dev --optimize-autoloader.
  4. Créez le fichier d’environnement. Copiez .env.example vers .env et listez les valeurs à modifier.
  5. Définissez les permissions des fichiers. Nommez les répertoires qui doivent être accessibles en écriture, par exemple storage/ et bootstrap/cache/, et expliquez pourquoi plutôt que de recommander 777.
  6. Lancez l’installateur ou les migrations. Montrez ce que demande chaque écran de l’installateur, y compris l’étape de la clé de licence.
  7. Configurez les tâches planifiées et les files d’attente. Donnez la ligne cron exacte et la façon de lancer ou de superviser les workers de file d’attente.
  8. Première connexion et premières tâches. Les identifiants par défaut, les trois premiers paramètres à modifier et comment envoyer un e-mail de test.
  9. Vérifiez l’installation. Une courte liste de ce qui doit désormais fonctionner, comme « le tableau de bord se charge », « un e-mail de test arrive », « la tâche planifiée apparaît dans le journal ».
  10. En cas de problème : des liens vers les cinq erreurs d’installation les plus courantes de votre page de dépannage.

Ajoutez une courte section distincte pour chaque configuration d’hébergement courante que vous prenez en charge : un VPS avec Nginx, un VPS avec Apache, un hébergement mutualisé avec cPanel, Docker. Si vous n’en prenez pas une en charge, dites-le. Les acheteurs peuvent aussi apprendre la démarche générale grâce à des guides comme comment installer une application web Laravel sur un VPS, mais votre guide doit tout de même couvrir les étapes propres à votre produit.

Rédigez une référence de configuration, pas seulement des commentaires dans .env

Les commentaires dans .env.example aident les développeurs, mais beaucoup d’acheteurs sont des chefs d’entreprise ou des développeurs juniors. Un tableau de référence répond en un seul endroit à la question « à quoi cela sert-il et quand dois-je le modifier ? ».

VariableValeur par défautRôleQuand la modifier
APP_URLhttp://localhostURL de base utilisée dans les liens et les e-mailsToujours ; indiquez votre vrai domaine en https
MAIL_MAILERlogMode d’envoi des e-mailsPassez à smtp ou à votre fournisseur avant la mise en production
QUEUE_CONNECTIONsyncDétermine si les tâches de fond s’exécutent immédiatement ou dans un workerUtilisez database ou redis sur les sites très fréquentés et lancez un worker
APP_TIMEZONEUTCFuseau horaire des dates et des tâches planifiéesIndiquez le fuseau horaire de votre entreprise

Le tableau ci-dessus est un exemple ; documentez chaque variable que lit votre produit. Faites de même pour les écrans de paramètres dans l’application : ce que modifie chaque paramètre et quelle est la valeur par défaut sûre.

Dépannage : rédigez les entrées autour de vrais messages d’erreur

Les acheteurs recherchent le texte exact qu’ils voient. Une page de dépannage qui utilise ces chaînes exactes comme titres est trouvée par les moteurs de recherche et par la recherche interne du site de l’acheteur. Utilisez ce format pour chaque entrée :

Erreur : SQLSTATE[HY000] [2002] Connection refused

Ce que cela signifie : l’application ne parvient pas à joindre le serveur de base de données.

Causes fréquentes : DB_HOST ou DB_PORT incorrect ; le service de base de données ne tourne pas ; l’hôte n’accepte que les connexions depuis localhost.

Comment corriger : vérifiez les valeurs dans .env, confirmez que la base de données tourne, essayez 127.0.0.1 au lieu de localhost, puis videz le cache de configuration.

Commencez par les erreurs que vous connaissez déjà : une page blanche avec le mode debug désactivé, l’erreur 500 après le téléversement, les erreurs de permissions sur le stockage, l’extension PHP manquante, les échecs d’authentification de la messagerie, le cron qui ne s’exécute pas et les échecs de vérification de licence. Ajoutez ensuite une nouvelle entrée chaque fois qu’un ticket en révèle une nouvelle.

Guide de personnalisation : répondez à « comment modifier X »

Les demandes de personnalisation sont la deuxième source de tickets, et de nombreux vendeurs y répondent une par une, indéfiniment. Documentez une bonne fois pour toutes les dix modifications les plus courantes :

  • Changer le logo, les couleurs et le nom de l’application.
  • Modifier les modèles d’e-mails et le texte des notifications.
  • Ajouter ou modifier une langue ou une chaîne de traduction.
  • Ajouter un champ à un formulaire et à la base de données.
  • Ajouter un élément de menu ou une page.
  • Changer la devise, le format de date et le format des nombres.
  • Connecter un autre fournisseur de paiement, de SMS ou d’e-mail.
  • Ajouter un rôle ou une permission.

Pour chacune, indiquez où se trouve le fichier, ce qu’il faut modifier et comment conserver la modification lors des futures mises à jour. Ce dernier point est important : si les acheteurs modifient les fichiers du cœur, chaque mise à jour devient un ticket de support. Orientez-les plutôt vers les points d’extension, les dossiers de surcharge ou la configuration. Notre guide sur le support, les mises à jour et la gestion des versions explique comment concevoir des versions qui permettent aux installations personnalisées d’être mises à jour.

Transformez les tickets en documentation chaque mois

La documentation devient obsolète et ne couvre jamais tout du premier coup. Une simple boucle mensuelle la garde utile :

  1. Étiquetez chaque ticket avec une catégorie : installation, configuration, utilisation, personnalisation, bug, avant-vente, autre.
  2. Une fois par mois, comptez les étiquettes. Choisissez les trois questions les plus fréquentes qui ne sont pas des bugs.
  3. Rédigez ou améliorez la page qui aurait répondu à chacune, en reprenant les mots de l’acheteur dans le titre.
  4. Répondez aux futurs tickets avec un lien accompagné d’un résumé d’une ligne. Si le lien ne résout pas le problème, la page doit être retravaillée.
  5. Corrigez le produit quand la même confusion revient sans cesse. Un message d’erreur plus clair ou une vérification dans l’installateur vaut mieux que n’importe quel document.

À titre d’exemple, un vendeur qui reçoit 40 tickets par mois et constate que 15 concernent la configuration des e-mails peut généralement en supprimer la plupart avec une bonne page et une étape de l’installateur qui envoie un e-mail de test.

Faites en sorte que le produit se documente lui-même

La meilleure documentation est celle que l’acheteur n’a jamais besoin d’ouvrir :

  • Des vérifications dans l’installateur qui testent la version de PHP, les extensions, les dossiers accessibles en écriture et la connexion à la base de données, et qui expliquent les échecs en langage clair.
  • Des messages d’erreur utiles qui indiquent quoi faire ensuite (« Le serveur de messagerie a refusé la connexion. Vérifiez MAIL_USERNAME et MAIL_PASSWORD dans les Paramètres »).
  • Une page d’état du système dans l’espace d’administration affichant les versions, l’état de la file d’attente, la dernière exécution du cron et les permissions du stockage. Les acheteurs peuvent en faire une capture d’écran lorsqu’ils ouvrent un ticket.
  • Un texte d’aide contextuel à côté des paramètres faciles à mal comprendre.
  • Des états vides qui expliquent l’action suivante (« Aucun membre du personnel pour l’instant. Ajoutez votre premier membre du personnel »).

Des règles de style qui rendent la documentation plus facile à suivre

  • Rédigez des étapes numérotées pour tout ce qui se fait dans l’ordre, une action par étape.
  • Montrez les commandes exactes et les chemins exacts, et indiquez où les exécuter.
  • Indiquez le résultat attendu après les étapes importantes, pour que les lecteurs sachent quand quelque chose a mal tourné.
  • Utilisez des captures d’écran pour les écrans de paramètres, et mettez-les à jour quand l’interface change.
  • Écrivez dans un anglais américain simple, avec des phrases courtes ; beaucoup d’acheteurs lisent via un outil de traduction.
  • Versionnez la documentation. Signalez les sections qui ne s’appliquent qu’à certaines versions et conservez des notes de mise à jour pour chaque version publiée.

Les principes de documentation de Write the Docs, gratuits, constituent une bonne liste de contrôle pour la clarté et la structure.

Liste de contrôle de la documentation avant la soumission

  1. Le README répond à : ce que c’est, les prérequis, le contenu du ZIP, le démarrage rapide, les identifiants par défaut et où obtenir de l’aide.
  2. Le guide d’installation a été testé sur un serveur vierge, avec une section pour chaque configuration d’hébergement prise en charge.
  3. La référence de configuration couvre chaque variable d’environnement et chaque paramètre important.
  4. Le guide utilisateur couvre les tâches principales de chaque rôle.
  5. Le guide de personnalisation couvre les dix modifications les plus courantes et la façon de les conserver lors des mises à jour.
  6. La page de dépannage utilise les messages d’erreur exacts comme titres.
  7. Le journal des modifications et les notes de mise à jour sont inclus.
  8. La documentation figure dans le téléchargement et en ligne.

Avant de soumettre, comparez avec la liste de contrôle de soumission de produit et les normes de code d’AppTrovo. Une fois votre documentation prête, votre fiche produit peut y renvoyer depuis la section des prérequis, ce qui aide aussi les acheteurs en phase d’avant-vente.

Questions fréquentes

Que doit contenir une documentation logicielle destinée aux clients ?

Au minimum : un README, un guide d’installation, une référence de configuration, un guide utilisateur, un guide de personnalisation et une page de dépannage avec des notes de mise à jour. Chaque document répond à une question différente : gardez-les donc séparés et reliez-les entre eux.

La documentation doit-elle se trouver dans le ZIP ou en ligne ?

Les deux. La copie dans le ZIP correspond toujours à la version que possède l’acheteur. La copie en ligne est consultable par recherche, facile à citer en lien dans les réponses du support et peut être mise à jour entre deux versions. Indiquez clairement à quelle version s’applique chaque page en ligne.

Quel niveau de détail un guide d’installation doit-il avoir ?

Suffisamment détaillé pour qu’une personne ayant déjà installé une application web, mais jamais la vôtre, puisse aller au bout sans vous contacter. Incluez les commandes exactes, les chemins, les permissions requises et le résultat attendu après chaque étape importante. Testez-le sur un serveur vierge pour chaque version qui modifie les prérequis.

Comment savoir quelle documentation rédiger en premier ?

Examinez vos tickets de support et les questions d’avant-vente. L’installation et la configuration passent généralement en premier, suivies des demandes de personnalisation les plus courantes. Si vous n’avez pas encore de tickets, installez vous-même le produit sur un serveur vierge et documentez chaque point où vous avez dû réfléchir.

Une bonne documentation réduit-elle vraiment les remboursements ?

Les installations ratées et les attentes non satisfaites sont des raisons fréquentes pour lesquelles les acheteurs demandent un remboursement, et des prérequis clairs associés à un guide d’installation testé répondent à ces deux problèmes. Les remboursements sur AppTrovo suivent la politique de remboursement, mais prévenir le problème coûte toujours moins cher que de traiter la demande.