This guest blog post was written by Neil Perlin, an internationally known consultant, strategist, trainer, and developer for online content in all forms from traditional online help to mobile.

Everyone in technical communication agrees that a content style guide is useful. But what is a style guide? What goes into these guidelines? In this blog post, I’ll look at those two questions and two more – what should a style guide not contain and how can MadCap Flare help with the creation and maintenance of your style guide.

What Is a Style Guide?

A style guide is simply a set of instructions for creating content. Those instructions usually focus on textual content but can refer to other types of content too, such as images, video, augmented reality, etc. Included will be a set of technical manual examples to serve as a content creation guide.


A style guide has two purposes. One is to define the authoring instructions. The second is to ensure that every author in a doc group follows those instructions in order to create a technical document that’s consistently worded, formatted, and accessed.

I can break the instructions down into two categories, content creation, and content presentation. Neither category is Flare-specific but each category can be supported by features in Flare itself. Read on…

What Goes into a Style Guide? And What Does Not…

Content Creation

There’s always the temptation to write a complete writing style guide – to recreate the Chicago Manual of Style or the Microsoft style guide. It’s a bad idea for several reasons.

You’ll make extra work for yourself writing and maintaining the instructions.

You’ll wind up creating a 100+ page style guide that is so overwhelming as to go unused.

There’s the risk of insulting your technical writer by assuming that they need such fine-grained guidance.

Instead, assume that your technical writer is a professional. You can then leave out anything basic that they should already know, such as the difference between active and passive voice and when to use each one, etc. Instead, focus on things that are either unusual applications of what they know or things that are peculiar to the mediums for which they're writing. A few examples…

  • Provide a list of accepted terms and, if necessary, their spelling. For example, specify if a sandwich is a sub, a hoagy, a torpedo, etc.
  • Give topics unique names that won’t cause confusion when they appear in a search hits list. By way of illustration – in the old days, PCs had two external disk drives, a 5 ¼” drive, and a 3 ½” drive. The user manual included sections on inserting the disk and removing the disk, and those sections each had the same name, “Inserting the Disk” and “Removing the Disk”. It didn’t matter that the names were identical because readers knew the context of the section they were looking at – the 5 ¼” drive or the 3 ½” drive. But when that user manual was put online, running a search would give two hits with the same name and no indication of which one to select. So authors leaned to change the section names to, for example, “Inserting the 5 ¼” Disk” and “Removing the 5 ¼” Disk”.
  • Consider if you need output-based terminology. For example, if you write for print output like PDF or for online output to be read on desktop-style monitors, you tell readers to do something “and press Enter.” However, more and more authors now create online output that will be read on mobile devices as well, where the terminology is “and tap Enter.” You not only need to keep this in mind when writing the content but also have to enable this wording change to occur technically and automatically.

Content Presentation

On the content presentation side, consider setting standards for large and small elements such as information types and their components.

On the large side, describe the information types that can be created such as content topics, procedure topics, reference topics, etc. (This isn't DITA, although the same principles apply.) For each type, describe the selection criteria to help authors decide which type to create for a given piece of content. If you can fit your content into a small number of consistent information types, it will be easier for readers to get accustomed to how the information is presented within the document.

On the small side, describe the properties of components that make up information types – styles. The CSS standard is incredibly deep and powerful, but most projects only use a small number of styles so this is easier and quicker than it may seem.

Using Flare to Create and Maintain Your Style Guide

If you’re new to Flare, you may not realize how many features Flare offers to support your style guide work. Some examples…

  • Variables and snippets let you define consistent terminology by creating re-usable chunks of content.
  • The stylesheet lets you define the properties for the information type components (and the table types as well).
  • The Template Manager lets you create your information type templates and add them to the Flare interface in a way that eliminates the risk of overwriting the templates.
  • The Flare Project Import feature lets you easily share all these features and others to multiple projects to ensure consistency of writing and presentation.

Summary

A style guide isn’t glamorous but if you need consistency in authoring and structure, it’s the technical writing software you need to deliver great documentation.