Close

Amélioration de la documentation

Vous venez de lancer un projet et vous êtes à présent sur le point de livrer de la documentation (autrement dit : c'est la m****).

Cela vous semble fastidieux à première vue ? Bien sûr, mais nous sommes là pour vous aider ! Vous trouverez ci-dessous de la documentation sur la documentation [(wink)] , un guide pas-à-pas agrémenté de conseils de pro, pour vous guider dans le processus.C'est parti !


Pourquoi devrais-je m'y intéresser ?

Pour faire simple : la documentation permet aux personnes de réaliser leurs tâches. Cependant, comme pour la plupart des choses inexplicablement extraordinaires, elle ne se contente pas d'aider les gens à faire avancer les choses. Grâce à elle, les utilisateurs et les équipes peuvent :

Dépenser moins d'énergie mentale

Faites avancer les choses sans trop réfléchir et en faisant le moins d'efforts possible.

Créer de la cohérence

Assurez-vous que vos lecteurs consomment les mêmes informations, processus et plans de manière cohérente.

Réduire la charge de travail

Intégrez rapidement et efficacement des coéquipiers afin qu'ils puissent faire avancer les choses en un rien de temps.

Améliorer l'image de marque

Mettez en avant la façon dont vous traitez vos clients externes et vos employés internes en apportant du soutien et en vous montrant utile.

Si vous n'offrez pas de valeur, personne ne se souciera de vous. Il vous appartient de déterminer comment vos lecteurs perçoivent les informations que vous proposez et de leur expliquer pourquoi ils devraient s'y intéresser.

Qu'est-ce que la documentation ?

La documentation porte bien son nom : il s'agit d'un ensemble de documents. Une boussole pour votre utilisateur final. Un playbook pour l'ingénieur en développement que vous êtes. D'un point de vue plus technique, la documentation est généralement constituée de texte ou d'illustrations qui accompagnent un logiciel. Ces documents servent de guide de référence expliquant le fonctionnement, l'exploitation et l'utilisation. Les équipes de développement peuvent se référer à la documentation lorsqu'il est question d'exigences produit, de notes de version ou de spécifications de design. Les équipes techniques peuvent utiliser la documentation pour détailler le code, les API, et consigner leurs processus de développement logiciel. En externe, la documentation prend souvent la forme de manuels et de guides de l'utilisateur destinés aux administrateurs système, aux équipes de support et aux autres utilisateurs finaux.

Toute documentation doit avoir comme objectif d'accomplir ces deux missions :

1. Informer les utilisateurs

2. Permettre aux utilisateurs de réussir à faire quelque chose

Lorsque vous commencez à rédiger de la documentation, définissez d'abord le sujet envisagé, ainsi que le but ou l'objectif pour aider votre public à comprendre ce qu'il lit dès le départ.

Types de documentation

Comme nous l'avons mentionné précédemment, la documentation se décline dans tous les formats et toutes les structures, et peut être interne ou externe. Selon le type de document, la voix, le ton, le format, les contributeurs, le public et le contenu varient. Voici les types de documentation les plus courants :



Documentation interne
illustration-documentation-equipe

Documentation d'équipe

La documentation d'équipe aide à donner vie au travail effectué, afin que les équipes puissent travailler… en équipe. Ces documents se présentent sous la forme de plans de projet, de calendriers d'équipe, de rapports d'état, de notes de réunion et de tout autre support dont une équipe peut avoir besoin pour travailler de manière fonctionnelle et efficace. Ce type de documentation est détaillé afin que tout le monde soit sur la même longueur d'onde.

illustration-documentation-reference

Documentation de référence

La documentation de référence forme les employés de l'entreprise à des thèmes, des processus et des politiques importants. Il peut s'agir de politiques conçues par le service RH, de processus juridiques pour l'embauche de fournisseurs externes, ou d'articles d'aide relatifs à la mise en place des avantages de votre entreprise. N'oubliez pas que la documentation de référence est rédigée par un petit groupe de personnes à l'intention d'un large public. Il est donc important que le contenu soit agréable à lire.

illustration-documentation-projet

Documentation de projet

La documentation de projet est, par nature, propre aux projets et donne la structure nécessaire au développement de produits. Elle comprend des propositions, des documents d'exigences produit, des directives ou des croquis de design, des feuilles de route ainsi que d'autres informations pertinentes nécessaires au développement. Elle inclut également les contributions des chefs de projets, des ingénieurs, des designers, et plus encore.



DOCUMENTATION EXTERNE
illustration-documentation-systeme

Documentation système

La documentation système précise le code, les API, ainsi que les autres processus qui indiquent aux développeurs et aux programmeurs les types de méthodes et de fonctions qui peuvent être utilisés dans le développement de logiciels spécifiques, ainsi que les limites et les exigences. Les snippets de code, tels que les exemples d'appels et de réponses API, jouent un rôle central dans ce type de documentation.

illustration-documentation-utilisateurs-finaux

Documentation pour les utilisateurs finaux

La documentation pour les utilisateurs est souvent la plus visible. Elle doit être facile à lire et à comprendre, et mise à jour à chaque nouvelle version du logiciel. Elle prend la forme de documents « README », de guides d'installation, de guides d'administration, de bases de connaissances produit et de tutoriels (les plus utiles de cette liste). Tout comme la documentation de référence, elle est rédigée par un petit groupe de créateurs, à l'intention d'un vaste ensemble de consommateurs. Il est donc important que son contenu soit agréable à lire.

Les exemples inclus à votre documentation offrent une valeur considérable à votre public. Ils font office de passerelle aidant à la compréhension de concepts et d'idées, et garantissent au lecteur que vous savez effectivement de quoi vous parlez.

Création de documentation

L'objectif ultime est de vous assurer que votre documentation est utile au lecteur. Vous trouverez ci-dessous un petit tutoriel pour vous guider lors de la rédaction de votre documentation, qui nous l'espérons, vous facilitera la tâche. Sympa, non ?

1. Faites des recherches

Qu'est-ce que les utilisateurs doivent savoir sur votre produit, votre projet ou votre API ? Utilisez votre outil d'analyses pour découvrir les recherches effectuées, parcourez des forums communautaires et des groupes de discussion en ligne, et effectuez des recherches sur les utilisateurs ainsi que des tests d'utilisabilité. Assurez-vous également de connaître votre produit, et de savoir comment répondre aux questions des utilisateurs et expliquer facilement les nouvelles fonctionnalités ainsi que les workflows.

2. Lancez-vous

Indiquez clairement les thèmes traités dans votre documentation et pourquoi le lecteur en tirera profit.

3. Capturez les informations

Créez un plan et rédigez votre contenu. Utilisez une voix et un ton appropriés (soyez humain !) vis-à-vis de votre public, et soyez cohérent et concis. Communiquez clairement les informations importantes.

4. Soignez la mise en page

Organisez votre page de sorte qu'elle soit facile à suivre du début à la fin. Éliminez le superflu et décomposez les longs paragraphes à l'aide d'éléments visuels tels que des diagrammes, des captures d'écran et des images.

5. Passez en revue

Obtenez un feedback complet. Assurez-vous que les réviseurs comprennent l'objectif de votre documentation. Cela vous permettra de découvrir des termes confus ou de signaler des étapes manquantes.

6. Publiez

Une fois les révisions et les modifications apportées, vous êtes prêt à vous lancer ! Publiez votre travail et restez à l'écoute de tout feedback et commentaire. La documentation n'est pas figée.

Enseignements clés

Comme vous pouvez le voir, la documentation ne se résume pas à rassembler des instructions et des mots. Il y a une logique à la folie, les amis. N'oubliez pas ces principes directeurs à chaque étape de la création de votre documentation :

Misez sur la concision

Votre documentation doit contenir la quantité d'informations nécessaires pour accomplir le travail sans créer de ticket d'aide. Fournissez des points clés et donnez aux lecteurs la possibilité d'approfondir.

Les visuels sont essentiels

Les visuels sont essentiels à la compréhension. La conception de produits, les exemples de code, les démos produits, les captures d'écran et les tutoriels vidéos aident grandement le lecteur à bien comprendre le concept, la manière de procéder ou la tâche à réaliser. Gardez également à l'esprit la mise en page, la lisibilité et les blocs facilement assimilables.

Cernez votre public

Mettez-vous à la place de l'utilisateur. Cernez votre lecteur, explorez son parcours utilisateur dans votre produit et votre documentation. Cela devrait toujours orienter votre contenu ainsi que la manière dont vous le rédigez.

Mettez-vous rapidement au travail

La meilleure documentation est claire, concise, informative et, surtout, elle apporte de la valeur à son public. Explorez des logiciels de collaboration en équipe tels que Confluence pour votre documentation, et consacrez moins de temps à la gestion pour vous concentrer sur le développement.

En savoir plus