Comment créer une documentation logicielle impeccable

Soyons honnêtes, créer de la documentation logicielle est une chose délicate. Chaque entreprise a son propre flux de travail et vous oblige à être très attentif afin de ne rien perdre d’important tout en rendant les articles aussi simples que possible. Heureusement, il existe plusieurs bonnes pratiques qui vous aideront à créer une documentation fiable avec plus de confiance. Offrez-vous le meilleur logiciel de rédaction technique et préparez-vous à apprendre !

1. Comprenez votre public cible et vos objectifs de documentation

Respirez profondément et expliquez pourquoi vous êtes sur le point de créer une documentation pour un produit logiciel. Cela semble être une question simple, mais il est très facile d’omettre les objectifs réels et les exigences du public cible. Votre mission est de mettre en évidence le bon objectif du document que vous allez créer. Voici comment procéder au mieux :

1. Commencer un document vierge.
2. Notez toutes les réponses qui vous passent par la tête.
3. Mettez en évidence les bons objectifs en fonction du portrait du public cible.

Votre compréhension du public cible doit être très claire car elle définit à quoi ressemblera votre document au final. Cela peut sembler trivial, mais vous devriez penser à de vraies personnes qui liront le document. Cela vous aidera à obtenir les bons résultats à coup sûr.

2. Mettez en surbrillance toutes les questions importantes

Chaque document technique doit aborder des problèmes spécifiques et répondre à toutes les questions que le public cible pourrait avoir lors de l’utilisation du logiciel que vous décrivez. Une fois que vous avez terminé l’étape précédente et déterminé qui est votre public et quels sont les principaux objectifs de la documentation, vous devez faire de votre mieux pour anticiper les questions que ces vraies personnes auront. C’est pourquoi il est si important de déterminer pour qui vous écrivez en premier.

Dans le document que vous avez créé pour la première étape, créez une section FAQ. Remplissez-le de questions afin de recueillir des idées pour le document final que vous créerez plus tard. Vous devez le considérer comme une phase de préparation, et non comme une partie du document que vous publierez, alors soyez patient et faites de votre mieux pour poser autant de questions raisonnables que possible.

3. Créer un plan de document

Si vous êtes sur le point d’écrire votre première documentation logicielle, vous devez prendre le temps de bien préparer la bonne structure à partir de zéro. Il est important qu’il n’y ait pas de modèle 100 % universel pour tous les produits logiciels, vous devez donc le créer en tenant compte des fonctionnalités du logiciel sur lequel vous écrivez. C’est là que les objectifs et le portrait du public que vous avez mis en évidence lors de la première étape vous seront à nouveau utiles.

Voici les points que vous devez inclure dans le plan de votre document :

1. Le titre du document et le « nom » de son public cible ;
2. Un résumé rapide du contenu du document ;
3. Les objectifs clairs de votre document ;
4. Exigences complètes pour les lecteurs (si nécessaire) ;
5. La liste des instructions, des solutions, des codes ou tout ce qui s’applique à votre situation ;
6. Chronologie de la création du document ;
7. Toutes les références applicables.

Soyez prêt à ce que la création d’un plan puisse prendre une journée entière, mais vous saurez à quoi le document doit ressembler mieux que quiconque à la fin. Faites appel à un graphiste pour faciliter la perception de votre plan et utilisez-le comme modèle pour le document que vous rédigerez.

4. Faites des recherches pour recueillir des informations

Vous savez peut-être tout sur le produit sur lequel vous allez écrire ou n’en avez aucune connaissance. Dans les deux cas, vous devez effectuer une recherche approfondie du produit pour recueillir des informations pertinentes à jour et valider ce que vous savez déjà.

Cette phase peut inclure des entretiens avec des PME (experts en la matière), l’évaluation de la documentation du produit logiciel existant, la recherche, etc. Vous devez traiter toutes les informations disponibles dans une base de données utilisable, puis répartir les données entre les points de votre plan. N’oubliez pas de conserver les références là où cela peut ajouter de la crédibilité au document final.

5. Créez le brouillon

Phew! Vous êtes maintenant enfin prêt à créer le brouillon du document. Assurez-vous d’avoir créé un plan suffisamment solide pour vous permettre de créer un brouillon substantiel. Si vous avez suffisamment d’informations initiales, la création du brouillon devrait être une tâche rapide et facile pour vous. Voici quelques conseils qui rendront le processus encore plus simple :

• Utilisez un langage simple ;
• Évitez les points ambigus ;
• Évitez de modifier le brouillon pour gagner du temps ;
• N’utilisez aucun jargon ;
• Écrivez autant que vous en avez besoin et rien d’autre ;
• Référez-vous au public cible et aux objectifs de votre écriture.

6. N’oubliez pas les visuels

Une fois le brouillon prêt, vous devez l’enrichir de visuels, y compris des illustrations utiles, des organigrammes, des captures d’écran du logiciel sur lequel vous écrivez, etc. Vous pouvez également insérer des liens vers le contenu intégré, tels que des vidéos et des éléments interactifs. Il peut également être utile de créer des brouillons de graphiques si nécessaire. Plus tard, votre graphiste les traitera dans un style unifié.

Il n’est pas nécessaire d’ajouter des visuels inutiles, alors assurez-vous que toutes les images que vous ajoutez vous aident à expliquer les concepts techniques, aident les lecteurs à mieux comprendre les fonctionnalités, améliorent la navigation dans le produit logiciel, etc.

7. Faites la « coupe finale »

Maintenant que vous avez un excellent brouillon avec des visuels, il est temps de modifier le document pour le transformer en un document final bien poli. Avant de commencer à modifier, décidez du nombre de séries de modifications dont le document a besoin pour vous assurer de ne rien manquer. Le processus d’édition peut impliquer de travailler avec un éditeur, une PME ou toute autre personne qui se trouve dans le contexte de votre rédaction technique. Si vous avez suffisamment accompli toutes les étapes précédentes, le nombre de modifications sera minime et vous donnera l’impression d’une bouffée d’air frais.

Pas de précipitation

Une bonne documentation logicielle ne peut pas être créée à la va-vite. Ce ne sont pas les dernières nouvelles qui seront inutiles demain, mais un wiki qui servira les objectifs du produit et de ses clients pendant des années. Suivez les meilleures pratiques décrites ci-dessus et ne refusez jamais de consacrer plus de temps à la planification et à l’édition. C’est le vrai chemin vers la perfection.