Most successful companies have one or more style guides, which may cover the use of logos and trademarks, the design of corporate communications, the layout and graphics of a presentation, or the writing of a manual.. To qualify and harmonize software applications, there are also style guides for user interface design.
All are important documents. They set the tone for how a company is perceived in its public communications and products.
Style guide for documentation
A documentation style guide is a set of rules for writing, formatting, and structuring documents. The implementation of such a guide ensures the consistency of an organization’s documents. A style guide then serves as a reference point. This is not a matter of pure grammar or “right” or “wrong” style, but of providing guidance in a field where there are several ways to express concepts, and it is good to choose one consciously. In the absence of a clear common policy, it is not uncommon to see noticeable and even embarrassing differences in style by the time documents reach customers.
Style guides also provide a way to present a brand consistently, with the same tone and language register, especially when many authors are involved. They also save time and resources by providing immediate answers to often recurring doubts and questions, as well as a critical reference for training new employees.
What does a style guide contain?
Below are some guidelines for what a style guide should contain.
- Vocabulary guidelines: should include a list of recommended technical terms (and prohibited alternatives), terms not to be translated, then terms to be avoided because they are potentially offensive, and clichés and expressions to be avoided.
- Grammar recommendations: includes using the active or passive voice, personal or impersonal, and gendered references.
- Stylistic rules for formats and usages: date (based on language), time, names, numbers, capital letters, bold, italic, underlined, bulleted and numbered lists, punctuation (quotation marks, exclamation marks, parentheses, semicolons), software code, and links/hyperlinks.
- Intranet and Internet: filename conventions, keywords, tags, and SEO guidelines.
- Logo: Rules for using and placing, dimensions, colors, background, as well as examples of uses and prohibited uses.
- Tools and templates: rules for using text and graphics programs, templates for manuals, presentations and notes, with related structural rules.
Standards and reference guides
For English, the style guides of some major software companies are public and can be a useful reference, such as Apple, IBM e Microsoft.
Various standards also exist for technical writing in different languages.
These references can help simplify writing a long list of customized rules. But keep in mind that their generality makes them difficult to apply in their entirety to all contexts. They generally need to be “filtered” to get a good result and make sense to use in daily practice.
Integration into development tools
Some programs for modular and structured documentation development also include some programmable settings for implementing style rules directly online. Whenever possible, this approach should be preferred. It allows for quick and easy compliance checks during the editorial process.
Collaboration
Finally, as with all rules to be followed, it is important to remember that the creation of a style guide is a collaborative process that must mature collectively throughout the organization in order to be used with conviction and produce the expected results.
If you do not yet have the Style Guide and this is a topic that might be of interest to you, please contact us for a free, in-depth discussion.
