Context

Readers need to assume that the documentation is written by s single person. This reduces distraction so that readers are able to concentrate on the content and find information easily.

Problem

How can a team organize themselves to document in a common style?

Structure

Publishing content from different authors is conducted by newspapers and magazines on a regular basis. These organizations employ style guides to deliver quality content. But style guides exists for many other industries, too.

Consistency in written documents increases the ease of reading.

A style guide provides answers to questions to support writers. These include

• Word choice and controlled vocabulary
• Mood and tone
• Product names, Abbreviations, and acronyms
• Capitalization and Punctuation
• Spelling and grammar
• Use of text formatting and typographical conventions
• Use of diagrams and graphics
• Use of templates and categories
• Information Architecture
• Maintenance procedures
• Source code organization, naming, and formatting

There may be different or adjusted style guides for different types of text. For instance the tone of answers in social media networks may be different to that found in printed manuals.

A style guide are constantly adapted and expanded. Problems authors encounter while writing should be noted and discussed. These discussions may result in an updated version of the style guide.

Advantages

The use of style guides has the following advantages:

• Easy reading
• Improves the perceived quality of the product
• Supports authors and therefore decreases the resource consumption to create quality texts

Disadvantages

Creating a style guide or just selecting one is time consuming

Applying a style guide also takes time. Typically documents also have to be proof read. But it may save time because authors, especially unexperienced ones, do not loose time by making style decisions. Think of an author trying to find similar text in the documentation to check how things have been decided in the past. A style guide is an easy to access resource.

For some documents, especially those only used internally, adhering to a rigid style guide may not be necessary. But even for those documents a style guide, loosely applied typically enhances the documentation and makes it easier to read.

Resources