Maintenant un cordonnier avec des bottes, ou comment nous avons obtenu notre propre guide de style

Je suppose que, chers lecteurs, dans votre travail, vous avez dû traiter de la documentation technique et, peut-être, même de ceux qui l'ont créée - des rédacteurs techniques. Et sur notre blog, vous pourriez rencontrer un rédacteur technique de l'équipe Veeam.

Aujourd'hui, nous passons au niveau suivant de compréhension du fonctionnement du développement de la documentation technique dans Veeam Software.

KDPV est trompeur - ce n'est pas un miracle, mais le même travail que tous les autres collègues R&D. Cependant, ceux qui créent des guides ont des mots magiques pour leurs guides sur la création de guides! Voici une telle récursivité.

Lisez plus dans l'histoire de ma collègue Daria Shalygin.

Bonjour, je m'appelle Dasha et je suis responsable de la qualité du contenu chez Veeam Software. Je suis responsable de la qualité du contenu créé par le service de rédaction technique de notre entreprise. En pratique, je suis rédacteur technique et éditeur dans une seule bouteille. Mes responsabilités incluent:

• diriger mes propres projets - comme tous les rédacteurs techniques, j'ai mon domaine de responsabilité, c'est-à-dire un certain nombre de produits pour lesquels je crée et gère la documentation;
• Formation du personnel de niveau junior - J'ai créé un cours d'introduction pour les débutants, que j'enseigne pour expliquer les règles de base pour la rédaction de la documentation;
• conseiller les employés de niveaux supérieurs (expérimentés et seniors) - J'ai prévu des séances quotidiennes au cours desquelles tout membre de notre équipe peut me poser des questions concernant la documentation (que ce soit la rédaction, la structure, etc.);
• — , , , .

Il y a seulement 3 ans, nous n'avions que 8 rédacteurs techniques. Quand quelqu'un de nouveau est venu, il a étudié les guides existants et a commencé à écrire dans la même veine. C'était un moment merveilleux où nous avions tous le même sentiment de beauté, et nous pouvions sans effort parvenir à une compréhension commune de la façon d'écrire la documentation de nos produits.

Le temps a passé, l'entreprise a grandi, il y avait plus de produits et il fallait augmenter le personnel des rédacteurs techniques. Aujourd'hui, nous sommes déjà 18 personnes, et nous ne prévoyons pas de nous arrêter là. Tout irait bien, mais tout à coup, il s'est avéré qu'avec tant de gens s'entendre sur le beau devient difficile. Cela prend du temps, du temps et encore du temps.

Afin de réduire les coûts énergétiques du transfert de connaissances vers les nouveaux arrivants, ainsi que de réparer une fois pour toutes ce qui est «beau» dans la documentation technique Veeam, il a été décidé de créer notre propre guide de style. Je dois dire que quelques esquisses sur le thème du style existent déjà depuis de nombreuses années sous forme d'articles sur Confluence et de notes marginales dans les cahiers, mais tout cela était désordonné, fragmenté, et, bien sûr, pour parler de toute facilité d'utilisation et pertinence de l'information n'avait pas à.

C'était:



Lorsque nous avons créé notre guide de style, nous avons pris comme base 3 grands guides, qui sont généralement pris comme exemple lors de la rédaction de la documentation: ( Chicago Manual of Style , Microsoft Manual of Style et DITA Best Practices), a étudié un certain nombre de guides de style tiers qui existent avec d'autres sociétés (par exemple, IBM Style Guide , Documentation Style Guide pour OpenSolaris et autres), a mené une étude des dernières tendances dans le domaine de la documentation - et a mélangé tout cela avec nos onze années d'expérience dans Veeam Software.

Il est devenu:



En conséquence, le Guide de style de rédaction technique Veeam comprenait des sujets d'actualité tels que la structuration du contenu par type de sujet, les principes de l'anglais clair, la ponctuation, les articles, la mise en forme, la création de captures d'écran et de diagrammes, la création de liens vers votre propre documentation et celle de tiers, ainsi que des rappels utiles pour tous les jours.

Avec l'avènement du guide de style, nous avons non seulement facilité le processus de transfert des connaissances aux nouveaux employés, mais nous avons également bénéficié des avantages suivants:

• éviter d'avoir à rechercher dans les reptiles de style tiers et sur Internet les réponses aux questions qui se posent régulièrement;
• résolution instantanée de problèmes controversés concernant la langue, la conception et la structure des documents;
• navigation pratique à travers votre propre base de connaissances;
• la possibilité de fournir des liens vers des sections spécifiques à des collègues d'autres départements qui travaillent directement ou indirectement avec la rédaction de textes (que ce soit le support ou le contrôle qualité).

Un mème célèbre sur la façon dont le style d'écriture change de façon spectaculaire après avoir travaillé en tant que rédacteur technique.Notre

guide de style a été créé par des locuteurs non natifs (locuteurs non natifs) et était destiné aux locuteurs non natifs. Néanmoins, il a été lu et vérifié par nos locuteurs natifs, linguistes marketing qui ont la formation appropriée, ont de longs textes écrits pour le site Web de l'entreprise et ont développé leur propre guide de style, également basé sur les principes des géants mentionnés. industrie.

Nous travaillons actuellement à élargir notre base de connaissances. Nous voulons créer des guides de style distincts pour les documents de référence tels que la référence de l'API REST et la référence PowerShell. Pour ces documents, le contenu doit être structuré d'une manière spéciale, et cela doit être corrigé afin de maintenir l'uniformité entre les produits.

Nous serons heureux si notre guide de style sera utile à d'autres entreprises qui sont toujours à la recherche de leur propre style. Je vous conseille de regarder la section avec des informations de base , qui, selon notre expérience, sont souvent nécessaires dans le travail - il y a beaucoup de choses intéressantes. :)

Veeam Technical Writing Style Guide (anglais)