Now a shoemaker with boots, or How we got our own style guide
Today we move to the next level of understanding of how the development of technical documentation in Veeam Software works.
KDPV is deceiving – this is not a miracle, but the same work as all the other colleagues from R&D. However, those who create guides have magic words your guides on creating guides! Here is such a recursion.
Read more in the story of my colleague Daria Shalygin.
Hi, my name is Dasha and I am Content Quality Lead at Veeam Software. I am responsible for the quality of the content created by the technical writers department of our company. In practice, I am a technical writer and editor in one bottle. My responsibilities include:
- running my own projects – like all technical writers, I have my area of responsibility, that is, a number of products for which I create and maintain documentation;
- Junior level staff training – I created an introductory course for beginners, which I teach to explain the basic rules for writing documentation;
- advising employees at higher levels (experienced and senior) – I have daily sessions scheduled during which any member of our team can ask me any question regarding documentation (be it wording, structure, etc.);
- conducting a control review – from time to time I selectively review the documents of our team members for formatting, errors, typos, inconsistencies with style and so on.
Only 3 years ago we had only 8 technical writers. When someone new came, he studied the existing guides and began to write in approximately the same vein. It was a wonderful time, when we all had about the same feeling of beauty, and we could effortlessly come to a common understanding of how to write documentation for our products.
Time passed, the company grew, there were more products, and there was a need to increase the staff of technical writers. Today we are already 18 people, and we do not plan to stop there. Everything would be fine, but suddenly it turned out that with so many people agreeing on the beautiful becomes difficult. It takes time, time, and again time.
In order to reduce energy costs for transferring knowledge to new arrivals, as well as to fix once and for all what is “beautiful” in Veeam technical documentation, it was decided to create our own style guide. I must say that some sketches on the theme of style have already existed for many years in the form of articles on Confluence and marginal notes in notebooks, but all this was disordered, fragmented, and, of course, to talk about any ease of use and relevance of the information did not have to.
It was:
When we created our style guide, we took as a basis 3 large guides, which are usually taken as a sample when writing documentation 🙁Chicago Manual of Style, Microsoft Manual of Style and DITA Best Practices), studied a number of third-party style guides that exist with other companies (for example, Ibm style guide, Documentation Style Guide for OpenSolaris and others), conducted a study of the latest trends in the field of documentation – and mixed all this with our own eleven-year experience at Veeam Software.
It became:
As a result, in Veeam Technical Writing Style Guide Topical topics such as structuring content by topic type, Plain English principles, punctuation, articles, formatting, making screenshots and diagrams, making links to your own and third-party documentation, and useful reminders for every day were included.
With the advent of the style guide, we not only facilitated the process of transferring knowledge to new employees, but also received the following advantages:
- preventing the need to search in third-party style reptiles and the Internet for answers to questions that arise on a regular basis;
- instant resolution of controversial issues regarding the language, design and structure of documents;
- convenient navigation through your own knowledge base;
- the ability to provide links to specific sections to colleagues from other departments who directly or indirectly work with writing texts (be it Support or QA).
A famous meme about how the writing style changes dramatically after you have worked as a technical writer
Our style guide was created by non-native speakers (non-native speakers) and was intended for non-native speakers. Nevertheless, it was read and verified by our native speakers, linguists from the Marketing department, who have the appropriate education, have long written texts for the company’s website and have developed their own style guide, also based on the principles of the mentioned giants industry.
We are currently working on expanding our knowledge base. We want to create separate style guides for reference documents such as the REST API Reference and PowerShell Reference. For such documents, content needs to be structured in a special way, and this needs to be fixed in order to maintain uniformity between products.
We will be glad if our style guide It will be useful to other companies that are still just in search of their own style. I advise you to look at reference section, which, in our experience, is often needed in work – there are a lot of interesting things. 🙂
