Le guide de style DevTools devient public

Le guide de style de la documentation Progress DevTools est désormais ouvert au public. Apprenez de notre processus et de notre produit final l'importance de la cohérence.

Les développeurs sont sans équivoque : une documentation bien entretenue est essentielle pour qu'ils adoptent et utilisent avec succès les outils logiciels. Le défi auquel nous sommes confrontés en tant qu'éditeur de logiciels est le suivant : comment vous assurer qu'un portefeuille de plus de 16 produits logiciels développés par plusieurs équipes et utilisés dans le monde entier sont non seulement bien documentés, mais également dotés d'une documentation cohérente et simple. à comprendre, sans être trop simpliste.

En février 2022, leGuide de style de la documentation de Progress DevTools a rejoint la famille des guides de style d'entreprise accessibles au public et est désormais disponible pour tous nos utilisateurs existants et futurs clients. Comme il contient des directives universellement acceptées par les rédacteurs techniques du monde entier, certaines parties peuvent également être utilisées par tous ceux qui créent et maintiennent du contenu en ligne, et toutes sortes d'organisations peuvent en bénéficier en le définissant comme point de départ pour établir leur propre guide de règles d'écriture. .

À propos du guide de style

Une documentation produit de qualité adhère à certaines pratiques d'écriture de base qui garantissent que le contenu publié est facile à lire, à comprendre et à apprendre. Devant résoudre des problèmes identiques lors de l'assistance de nos collègues dans leurs efforts de maintenance de contenu, l'équipe de rédacteurs techniques de Progress s'est attachée à établir un ensemble de règles assurant la cohérence de la documentation produit dans toutes les équipes DevTools.

Les directives de rédaction de la documentation de Progress DevTools sont utilisées pour créer et étendre la documentation de tous nos outils de productivité pour développeurs, de nos bibliothèques de composants d'interface utilisateur .NET et JavaScript à Fiddler et Unite UX.

La mise en œuvre pratique de ces recommandations est un processus continu et nécessite des efforts continus. Dépassant nos attentes les plus audacieuses, les équipes de développement ont relevé le défi. Non seulement elles appliquent les directives, mais elles priorisent également les grands projets de documentation de qualité tels qu'une refonte générale du contenu des produits matures.

Le guide de style DevTools contient deux types de bonnes pratiques que nous, en tant que créateurs de documentation, appliquons lors de la création, de la modification ou de la maintenance de la documentation du produit :

L'histoire

Nous avons le guide de style DevTools depuis sept ans. Au cœur de sa création se trouvait la tâche de définir les grandes lignes d'une documentation cohérente entre les produits. L'utilisation d'une structure visuellement logique réduit considérablement le temps que les utilisateurs passent à s'orienter dans le contenu sur lequel ils atterrissent et le réduit à environ sept secondes.

Nous, créateurs techniques de diverses équipes de produits, avons travaillé pendant plus d'un an pour passer au crible les cas d'utilisation les plus fréquents qui devaient être traités, tels que les approches pours'adressant directement à l'utilisateuretéviter la voix passivepour ajouter plus de clarté.

Nous avons dû trouver l'équilibre entre ce qui était important pour fournir une documentation bénéfique à nos utilisateurs, établir des règles assurant une communication technique au plus haut niveau et gagner l'adhésion de nos collègues pour les suivre. Cela a pris des mois de travail, mais finalement le guide de style DevTools était prêt pour un usage interne, et nous l'utilisons depuis des années.

Et puis, nous avons décidé de le publier.

Pourquoi le rendre public ?

Nous considérons la documentation comme un produit à part entière, et elle fait l'objet d'un soin, d'une itération et d'une amélioration constants. Nous voulons donner à tous les utilisateurs la possibilité d'avoir leur mot à dire et d'indiquer explicitement le contenu qu'ils attendent et qu'ils aimeraient trouver, de la structure d'un article à l'essence de son contenu. Notre politique a toujours été de permettre aux utilisateurs de contribuer de manière transparente à notre documentation via les requêtes d'extraction GitHub, mais ils ont maintenant le plan pour le faire plus facilement, en douceur et de manière cohérente.

Nous prenons au sérieux non seulement nos produits, mais aussi notre documentation. lePousser l'enveloppeprix de catégorie dans leConcours des meilleurs sites Web ASP 2020que Progress a remporté l'a prouvé en reconnaissant nos efforts pour améliorer la documentation de nos produits.

Pourquoi les lignes directrices

Ne demandez jamais à un rédacteur technique pourquoi la documentation produit doit être cohérente. Vous jouez avec le feu et vous risquez d'entrer dans une dispute sans fin.

Blague à part, les sciences cognitives l'ont : lors de l'apprentissage d'un sujet, le cerveau perçoit les informations plus rapidement et plus facilement lorsqu'il reçoit le même type de contenu de la même manière. Par conséquent, l'une des lignes directrices conseille d'utiliserstructures parallèles lorsque l'on liste des éléments logiquement équivalents.

Par exemple, si vous commencez la première entrée par un verbe, commencez toutes les entrées par un verbe. Dans le même ordre d'idées, suivez les deuxième et troisième recommandations : si vous commencez l'entrée par une majuscule, mettez toutes les entrées en majuscule ; si vous terminez la première entrée par un point, terminez toutes par un point. Voici une démonstration simple :

Appliquez l'une des approches suivantes :

• Mettre à jour l'application.
• Réinstallez l'application.
• Supprimez complètement l'application.

Outre une représentation visuelle intuitive du flux logique d'un sujet, nous avons établi des modèles qui répondent aux spécificités du type d'article et fournissent les informations dont les utilisateurs ont besoin pour résoudre un scénario spécifique ou gérer un problème particulier.

Des exemples parfaits sont lesArticles de la base de connaissances (KB)qui incluent par thème des informations sur la manière d'obtenir un scénario souhaité ou de contourner un état actuel de configuration, et sur la manière de gérer les problèmes liés au dépannage.

Par exemple, dans son corps,un scénario pratique de la base de connaissances comprend la description de ce dont un utilisateur peut avoir besoin ainsi que sa mise en œuvre dans le projet. D'autre part,une rubrique de dépannage de la base de connaissancesfournit le message d'erreur que les utilisateurs peuvent recevoir, le cas échéant, ainsi que la cause de son apparition.

Ce que tu peux faire

Contribuez au contenu. C'est ainsi que vous pouvez nous aider à fournir des informations ciblées et utiles qui aident les utilisateurs à atteindre efficacement leurs objectifs. Sur la base de cette collaboration, nous pourrons identifier ce que les développeurs attendent de la documentation, puis travailler sur des étapes concrètes pour le fournir plus précisément.

Pour des commentaires et des suggestions sur le guide de style DevTools lui-même ou avec des idées générales d'amélioration de la documentation, contactez-nous àtechwriters@progress.com.

Pour soumettre une suggestion d'amélioration d'un article de notre documentation, cliquez sur leAméliorer cet articlesur la page pour ouvrir une demande d'extraction, ou sélectionnez leContactez le supportpossibilité pour l'équipe d'assistance de prêter main-forte au processus.

Vous pouvez toujours soumettre vos précieux commentaires sur une page de documentation spécifique via le Cet article a-t-il été utile? Oui Nonformulaire afin que les équipes puissent opérer dessus et mettre à jour le contenu, respectivement.

Cela dit, bonne lecture !