Erreurs courantes dans les documents rédigés par un ingénieur et comment les corriger

Au cours des six derniers mois, notre équipe de développement a adopté l'approche "docs-as-code" (vous pouvez en savoir plus sur notre parcours dans ce article ). En examinant régulièrement la documentation créée par mes collègues de la division technique, j'ai compilé une liste des problèmes les plus courants rencontrés lors de la rédaction de documentation technique.

Dans l'article, je vais vous montrer comment résoudre ces problèmes en utilisant les outils de l'approche "docs-as-code".

Problème 1. "La rédaction de documents n'est pas sous notre responsabilité"

Traiter la documentation au cas par cas, c'est comme se tirer une balle dans le pied pour toute l'équipe de développement. Si l'équipe n'a pas la capacité, c'est une raison impérieuse de rendre la maintenance de la documentation plus prévisible et axée sur la technologie.

Réparer:

• Intégrer l'approche « docs-as-code » au développement de la documentation. De cette façon, vous pouvez mettre à jour la documentation de manière itérative, parallèlement à la base de code, sans risquer d'accumuler une dette technique.
• Développez ou intégrez un espace ou une plate-forme pouvant rendre des documents techniques et servir de source unique d'informations.
• Utiliser un environnement de développement intégré (IDE). Un IDE vous permet d'incorporer des plugins et de créer des scripts personnalisés pour le développement de la documentation. IDÉE est un excellent outil pour la rédaction de documents, mais vous pouvez avoir vos favoris parmi les applications.
• Installez un plugin de vérification orthographique pour vous protéger contre les fautes de frappe. L'ajout du plugin à votre IDE est un processus rapide et facile.
• Adoptez les directives internes spécialement conçues par votre entreprise, en tenant compte des idées de la communauté de rédaction technique (si vous en avez), pour établir une approche standardisée pour le développement de la documentation au sein de l'entreprise. Le respect de ces directives rationalisera le processus de documentation, ce qui vous fera gagner du temps pour déterminer quoi et comment écrire avec précision.
• Automatisez les vérifications en fonction des directives afin de réduire ou d'éliminer considérablement le temps d'examen des documents.
• Modélisez tout ce qui est possible et mettez-vous d'accord avec l'équipe sur la standardisation des composants de la documentation.

Je vous proposerai des ressources précieuses qui renforceront votre confiance tout en travaillant avec la documentation technique. Je pense que ces ressources sont suffisamment complètes pour vous permettre de gérer efficacement les documents techniques :

• Le " Guide de style de la documentation pour les développeurs Google " sert de manuel complet pour la documentation des développeurs. Il couvre tout ce que vous devez savoir sur le formatage, la ponctuation, la liste et l'ajout de blocs de code. Ce guide est suffisant et a été une référence précieuse pour développer nos directives internes, à partir desquelles nous avons emprunté quelques les meilleures pratiques.
• " Documents pour les développeurs " est un livre incontournable pour toute personne impliquée dans le travail avec la documentation des développeurs, qu'elle soit en train de la développer, de l'écrire ou de la maintenir. Le livre présente plusieurs auteurs renommés et estimés dans le domaine de la rédaction technique.

• " Docs Like Code " par Anne Gentle, rédactrice technique, est un guide pratique qui présente la culture de la documentation dans OpenStack. À travers des exemples pratiques, l'auteur explique pourquoi la documentation doit être gérée dans GitHub et comment mettre en œuvre des processus technologiques pour une documentation efficace. Le livre offre également de précieuses des informations sur la rédaction de documentation professionnelle, que vous soyez développeur ou rédacteur technique.

• Je mentionnerai également les directives internes pour la rédaction de la documentation technique, qui devraient inclure des modèles et des règles de formatage. De telles directives existent dans chaque entreprise. En règle générale, ils sont développés en collaboration avec un rédacteur technique pionnier et des champions de la documentation de développement et évoluent à mesure que la culture de la documentation au sein de l'équipe se développe.

Problème 2. Rédaction de documentation en solo

Le développement de l'intégralité de la documentation seule, puis sa soumission pour examen comporte le risque de créer une documentation redondante ou non pertinente qui peut ne pas correspondre à l'objectif visé.

Réparer:

• Commencez toujours par un aperçu et partagez-le avec votre chef d'équipe, votre propriétaire de produit, votre rédacteur technique ou tout collègue désireux de donner son avis d'expert.
• Écrivez étape par étape et attribuez des demandes d'extraction pour examen aux mêmes collègues mentionnés ci-dessus.
• Recueillir et travailler sur les commentaires.
• Considérez les commentaires. Et allez-y doucement sur le ton de la voix de l'examen, parfois il peut être dur, mais ce n'est qu'une particularité du processus d'examen.
• Ne négligez pas le flux de documentation. Vous trouverez ci-dessous le flux général adopté dans notre entreprise, mais les fonctionnalités de ce flux peuvent dépendre d'une équipe de développement ainsi que de l'entreprise :

Question 3. "Ceux qui ont besoin de comprendre comprendront"

De temps en temps j'entends des équipes : « j'écris pour l'équipe de développement », « ceux qui ont besoin comprendront », « c'est ainsi que cela a évolué historiquement au sein de notre équipe ».

Mais le jargon professionnel et les anglicismes exigent justesse et cohérence. Leur utilisation excessive peut conduire à une documentation ressemblant aux notes d'un ingénieur fou.

Pour la documentation, utilisez les mots et les structures les plus simples possibles. L'un des grands principes est l'écriture pour le défilement. La documentation peut être difficile à rédiger car elle est souvent volumineuse, mais les lecteurs la parcourent rarement d'un bout à l'autre. Au lieu de cela, ils ont tendance à faire défiler ou à utiliser la recherche par mot-clé. Par conséquent, le texte doit être facilement compréhensible lorsqu'il est ouvert à partir de n'importe quelle partie.

Réparer:

• Vérifiez les termes anglais et le jargon professionnel à l'aide de dictionnaires et de normes en vigueur (ou simplement sur Google). Si un mot existe dans le dictionnaire, écrivez selon les règles d'orthographe de votre langue.
• Si le mot n'est pas présent dans la langue, écrivez-le dans la langue d'origine et fournissez une traduction dans votre langue entre parenthèses.
• Ajoutez le mot à la section glossaire et les abréviations à la liste des abréviations et acronymes. Ceci est particulièrement important pour les abréviations "propriétaires" (peu importe ce qui est mentionné ou écrit sur PO, sa signification est toujours l'une des questions courantes lors de la lecture de la documentation).
• Cohérence - respectez le style d'écriture et les abréviations choisis dans toute la documentation (mieux pour toute la documentation disponible dans votre entreprise).
• Planifiez soigneusement la navigation dans le document. Il devrait y avoir un moyen rapide de trouver la section pertinente sans avoir à lire l'intégralité du document. Par conséquent, il est essentiel de bien structurer le contenu avec des titres clairs et concis. Des modèles de documentation interne doivent être développés pour plus de simplicité et de commodité.

Problème 4. Rédaction simultanée de documentation à plusieurs endroits

Pour la documentation, avoir une seule source de vérité - un espace où vous pouvez trouver les informations nécessaires sans vous soucier de leur exactitude est crucial. Pour notre documentation technique, une plate-forme développée en interne sert d'espace. Éviter la fragmentation de la documentation dans différents espaces est essentiel pour éviter d'induire quiconque en erreur avec des informations obsolètes.

Réparer:

• Avant de publier de la documentation technique n'importe où, assurez-vous qu'elle n'existe pas ailleurs, s'il s'avérait que l'entreprise utilise plusieurs espaces de partage de connaissances.
• Archivez ou supprimez (si vous en êtes propriétaire) la documentation technique obsolète. Si vous craignez une suppression prématurée (par exemple, en raison de liens externes vers la page), ajoutez une légende indiquant que la page est obsolète et l'emplacement actuel de la documentation des documents valides, où d'autres mises à jour doivent être effectuées.
• Si vous rencontrez des informations ou des idées précieuses, ajoutez-les à la documentation. Ne le laissez pas dans Slack ou ailleurs, en particulier dans les discussions privées. Des connaissances qui méritent d'être partagées !

Posté par Anna Gontcharova