Les standards de la documentation à suivre

Les standards que vous suivez varient en fonction du type de documentation que vous créez. Voici quelques types communs, ainsi que des suggestions sur les modèles que vous pouvez utiliser pour établir vos standards.

Tout projet se déroulera plus facilement lorsque toutes les personnes impliquées sont en phase. Tous les membres de l'équipe travaillant sur un projet ont besoin d'une source de référence unique à laquelle ils peuvent se référer à tout moment. Sans un plan de projet documenté, les membres de l'équipe peuvent perdre la vue d'ensemble et finir par perdre du temps.

Pour accélérer et standardiser la documentation de projet, vous pouvez utiliser ce modèle proposé par Confluence. Vous consignerez alors systématiquement les informations clés sur chaque projet.

Les membres de votre équipe perdent-ils du temps car ils doivent constamment expliquer aux autres comment faire les choses ? Ou vous êtes-vous déjà retrouvé acculé lorsque la seule personne qui savait réaliser une tâche ou un processus clé était absente ?

Ces scénarios montrent l'importance de la documentation d'aide. Fondamentalement, tout ce que votre équipe fait de façon répétée doit être documenté de façon à ce que tous ses membres puissent accomplir cette tâche ou ce processus.

La documentation d'aide est plus efficace, et bien plus simple à créer, lorsque vous avez établi des standards. Une fois de plus, c'est là qu'un modèle s'avère très utile. Par exemple, le modèle de Confluence pour les articles d'aide vous donne la recette pour documenter les processus.

La documentation pour les logiciels et autres produits techniques peut expliquer le fonctionnement du produit, comment l'utiliser, comment il a été créé et comment il a été constitué.

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.

La documentation technique a tendance à être longue, détaillée et mise à jour fréquemment. Il est donc particulièrement important de disposer des bons outils pour garantir l'exactitude et gagner du temps. Par exemple, vous pouvez utiliser des modèles existants dans Confluence ou créer les vôtres. Confluence propose également des macros qui facilitent la mise à jour ou la réutilisation du texte.

Quel que soit le type de documentation que vous créez, quelques compétences clés vous permettront de vous assurer que votre travail répond à vos standards de documentation et qu'il est utile aux utilisateurs.

• Organisation : connaître les informations que vous souhaitez documenter est une chose. Les présenter d'une manière simple à suivre en est une autre. Outre l'organisation des informations dans un ordre logique, il est également important d'utiliser des éléments tels que des en-têtes de section et des listes à puces pour guider les utilisateurs de votre documentation.
• Clarté : une documentation claire et facile à comprendre nécessite de choisir le niveau de détails approprié. Trop peu d'informations peut être tout aussi déroutant qu'une multitude de données. Afin de rendre votre documentation plus claire, soyez méticuleux avec votre grammaire, évitez le jargon et choisissez des mots spécifiques plutôt que des mots vagues (comme « souvent »).
• Cohérence : faire attention à la cohérence est l'une des choses les plus utiles que vous pouvez faire pour les personnes qui utiliseront votre documentation. Par exemple, un utilisateur suivra plus facilement votre documentation d'aide si elle est rédigée de la même manière que d'autres documents d'aide de votre organisation.

La mise en place de standards ne vous aide pas seulement à créer une meilleure documentation, mais aussi à la distribuer plus efficacement.

Pour être utile, la documentation doit être accessible à toute votre équipe. Vous ne voulez pas que les membres de l'équipe consignent les informations importantes sur leurs disques durs individuels. Vous ne voulez pas non plus qu'ils aient à compter sur une seule copie imprimée cachée dans une armoire de rangement quelconque. Les situations comme celles-ci sont source de confusion et d'inefficacité.

Par exemple, les membres de l'équipe qui utilisent différentes versions d'une documentation peuvent avoir des problèmes de communication ou se créer mutuellement du travail supplémentaire. Autre exemple, une personne qui travaille à distance peut avoir besoin d'accéder à de la documentation qui existe uniquement sous forme physique au bureau.

En standardisant la manière dont vous stockez et distribuez la documentation, vous pouvez éviter ces problèmes. La meilleure solution ? Disposer d'un dépôt centralisé, d'un endroit unique où tout le monde sait rechercher les informations les plus à jour. Mais au-delà du simple fait de rassembler toutes les informations en un seul et même endroit, il faut également que les personnes y trouvent facilement ce qu'elles recherchent.

Chez Atlassian, ce dépôt centralisé, c'est Confluence. Les fonctionnalités telles que la recherche performante, les arborescences de page structurées et l'archivage de pages garantissent que le contenu est facile à trouver, toujours à portée de main et à jour.

Dans Confluence, chaque équipe ou projet dispose d'un espace pour organiser la documentation connexe. Il est possible de créer une hiérarchie de pages pour conserver toutes les informations organisées et visibles depuis l'arborescence de page. Les employés peuvent voir les espaces ou sous-pages dont ils ont besoin pour se tenir à jour lorsque le contenu est modifié. Pour distribuer un espace ou une page en particulier, vous pouvez utiliser le bouton Partager ou commenter une page et mentionner d'autres membres de l'équipe. Toutes les pages ouvertes dans Confluence sont consultables par les autres employés, et ils peuvent utiliser des filtres pour affiner leur recherche par créateur, date de publication ou espace.

Vos documents individuels doivent être mis à jour de manière cohérente ; il en va de même pour votre système de classement et d'organisation de la documentation. N'oubliez donc pas d'établir des standards dans ce domaine également. À quelle fréquence devez-vous réexaminer votre archive de documents et la ranger ? N'hésitez plus et réservez des créneaux dans le calendrier.

Maintenant que vous disposez d'une vue d'ensemble des standards de documentation, vous pouvez commencer à élaborer ou à réviser les consignes pour les types de documentation dont votre équipe a besoin. Le temps que vous consacrez à l'élaboration de ces standards n'est pas perdu : vous accélérerez ainsi la rédaction et rendrez la documentation plus utile pour votre équipe.