Without a style guide, it will be hard to create great technical content. No matter how different your documents may be, a style guide will help your team of technical writers to ensure consistency within all your documentation. You may write for different target audiences, but all of your documents have to be based on one style guide. It will be the basic guiding document for the whole bulk of your technical content. This blog will explain how a style guide can be useful for your company and customers.
What Is a Technical Writing Style Guide?
You may have noticed that having a distinctive style is like having a special voice. It works as if you have developed a new language – a language you use to communicate with your target audience. This language includes wording and all your documents' general pattern and layout.
A particular style helps readers to associate your content with one source. It makes your products more recognizable to the customers. To achieve this effect, you need a technical writing style guide, a fundamental document to help you build and expand your company knowledge base and make your content consistent.
A style guide is a reference document containing a collection of rules for writing and designing documents.
The purpose of the document is to serve as an outline and a list of requirements for creating new documents and rewriting and updating the existing ones. It is a ‘frame’ that is aimed to ensure that everything produced by your technical writing team is consistent in terms of style.
The requirements listed in this reference guide refer to the following major areas:
- Syntax (recommendations concerning punctuation, capitalization, abbreviations and shortenings, etc.);
- Formatting (rules for presenting numbers, dates, tables, etc.);
- Design (a large block of information disclosing the company philosophy concerning the color palette, illustrations, screenshots, photos, diagrams, etc.).
These recommendations will help your team of technical writers produce content that is uniform and appealing to the eye of the reader. It will be great if your corporate style guide includes samples, templates, or examples that will help tech writers work faster and avoid the most common mistakes.
Why Is a Technical Writing Style Guide Important?
If you are a practicing technical writer, you are probably subscribed to many online forums or blogs where you follow a thread or two discussing using single or double ‘l’ in American or British English or using impersonal pronouns like ‘they’ in official documents. You know pretty well that such issues emerge in your practice on a routine basis, and you have to solve such problems every time they occur.
A couple of days ago, I witnessed a real ‘fight’ between two writers from different cultures. They discussed which sign to use to separate decimals: a dot or a comma. The fact is that in some countries, the correct sign is a dot, while in others, it is a comma.
With a style guide, these questions won’t arise. They will be solved once and forever in the company reference book, and you and your colleagues will only have to follow the established order.
As a result, technical writing will become more efficient, and your documents will start looking uniform. You will probably need some training, as not all of your writing staff will consult the style guide in the beginning. But quite soon, they will adopt this habit. You will only have to show that it will save them a lot of time and effort if they follow the common rules and standards from the start. They will no longer have to discuss every ambiguous moment each time they come across it. All the tricky issues will be addressed in the guide.
Let’s now have a look at the writing process from another standpoint. They say a problem shared is a problem halved. However, the larger the number of authors who work on one document, the more vulnerable the content becomes in terms of style. Ironically, the more people are involved in the work, the larger the amount of inconsistencies.
Using a guide is a real remedy in this case. It is especially effective if you have several assignees working on the same document. They will all refer to the same set of rules and requirements, and the whole complex process of working in a large team will become less confusing.
Another advantage of a style manual is that it is indispensable in the onboarding process. It can be used as a training tool for new employees. At first, they will have to refer to it quite often, but soon, they will be able to format and design documents with their eyes closed.
Steps to Write Technical Writing Style Guides
The information presented below cannot be limited to the listed steps. They can be regarded as a recommendation, and the information in your corporate technical writing style guide can be more comprehensive.
The first step is the most general one. At this stage, you have to divide all the style-pertaining information into two large blocks: the visual and written content.
The visual block refers to your company’s branding policies. It describes the company color palette, logo, fonts, backgrounds, etc., that should be applied to all the published content.
The written part is text proper and its formatting rules (page setup, headlines, lists, pull quotes, etc.). The written part also covers the general tone of the publications, like neutral, business-like, or casual.
In the next step, the two blocks (concerning the visual and written information) should be filled with the requirements you want to include in the style guide. Putting it differently, the second step is formulating the requirements.
Most people think that formulating the requirements for the written part is the most challenging thing. In fact, it is the most transparent and clear part of creating a style guide. The thing is that this information has already been described in many internationally known style guides like the Publication Manual of the American Psychological Association (APA), the Modern Language Association's MLA Style Manual, and the Chicago Manual of Style (CMOS).
These are the most frequently used style guides in academic writing, and the technical language is very close to it. So, don’t hesitate to use the information from these guides in your company style guide. These most advanced style guides contain ready-made information concerning such issues as (APA):
- Paper format (font, headings, line spacing, margins, order of pages, page header, paragraph, alignment and indentation, title page setup);
- In-text citations (paraphrasing, quotations, etc.);
- Mechanics of style (abbreviations, capitalization, italics and quotation marks, lists, numbers, punctuation, spelling and hyphenation);
- Bias-free language (age, gender, racial and ethnic identity, etc.);
- Tables and figures (figure setup, sample figures, sample tables, table setup);
- Grammar (active and passive voice, singular “they,” verb tense, as well as other issues).
The list above can be very helpful in shaping the part of your style guide that refers to text. As for the visual part, it is more company-specific and has to be developed individually.
In the third step, you will have to familiarize your writing team with the style guide. You can do it using different methods, but the most obvious one is to assign it to the company knowledge manager who will hold a series of trainings on using the guide. The knowledge manager will also have to make sure everyone has access to the guide.
ClickHelp and Technical Writing Style Guides
In your practice, you will have to write different documents appealing to different target audiences (both potential customers of your products and in-house audiences). These may be user manuals, quick start guides, white papers, employee handbooks, PRDs (product requirement documents), etc.
Some of these documents may look very similar. For example, you may have very similar PRDs for different versions of one product. Actually, they will be almost the same docs but with different accents.
ClickHelp is an online documentation management platform based on the principles of single sourcing and content reuse. It means you can have one basic document (a source PRD like in the example above) and publish different versions of it.
Besides, ClickHelp offers snippets and variables that will help you change the document so that some elements are visible in one publication and invisible in the other. This will help you to make different accents in different versions of your documents.
Let’s take a different example. For instance, there is a company that produces gearboxes and compressors. You have a standard catalogue containing all the information on gearboxes and compressors. However, one segment of your target audience is interested only in compressors. In ClickHelp, you can edit the source document so that only the content concerning compressors will be visible in the publication.
ClickHelp is especially convenient for publishing docs in different formats (HTML, PDF, doc, docx, etc.). As a result, your customers will be able to open your files from a smartphone, a tablet, or even an E-book.
ClickHelp is extremely useful for styling the visual appearance of your content. The ready-made templates are available in ClickHelp and will make documentation branding much easier. If using templates is not enough for you and you want to implement a more profound approach to branding, you can open and edit the CSS files that come together with every project you create in the system.
Conclusion
If you don’t have a style guide in your company, it’s high time you start thinking about introducing one in your content creation process. A style guide will help to make your documents more predictable and, consequently, more readable. This effect is achieved through developing the common conventions for your company authors and reviewers. If you manage to introduce a style manual in your company, you will be able to streamline and control your writing process.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices