Use a style guide as a strategic tool

You can use a corporate style guide to enforce the strategic development of your documentation.

That’s my observation as we’re currently moving towards structured, topic-based authoring. The reasons for the move are pretty much the usual ones: To offer more consistent, less redundant documentation that’s easier to use, more efficient to create and maintain and also easier to collaborate on.

To ease in the introduction of topic-based authoring, we drafted a style guide for documentation which now prepares the way for topics. For example, we included specific guidelines for writing headings of manual sections (most of which will turn into topics) among the content guidelines:

  • Headings should preferably be unique, if possible.
  • Headings should be comprehensible when they appear by themselves in search results.
  • Headings of sections that instruct users to do something (which will turn into procedural topics) should start with a verb in the imperative, for example: “Set up a server”.
  • Headings of sections that combine several such instruction sections (which will turn into process topics that are parents of procedural toipcs) should start with a gerund verb, for example: “Setting up the installation”.

– The way I describe it makes it sound more deliberate than it actually was. The attitude was more like: Well, we’ll eventually move to topics, anyway, we might as well anticipate the new structure in the styles. We rolled out these guidelines before every writer had received training in topic-based authoring.

Now as we are moving closer to converting existing user manuals to topic collections, we find that many recent manuals which use the style guide not only spell “check box” consistently as two words, not one, but they are also well-prepared to be converted to topics!

How do you use your style guide? Does it only enforce writing and layout conventions, or does it also have a strategic element? Feel free to leave a comment.

7 Responses

  1. How many pages? How usable?

    • The style guide comes to about 80 pages. And much of it is reference material which you need to know is in there, but needn’t necessarily learn it by heart unless you use it frequently.

      But it does raise the issue that something as strategically as important as topics tends to blend in with the rest and, unless flagged properly, may be overlooked!

  2. Hi – I’m also a technical writer working in Germany. Glad I found your blog.

    My style guide is more of a publishing guide, as it has a pretty wide scope. I have a section for my content strategy ideas, including topic structure, audience definitions, goals of the content/users/company, etc. Another section is for processes such as how and where to publish, how to scope a feature to write about, how and where to track my work, etc. Another section is for formatting and style guidelines, including corporate identity guidelines for logos, colors, fonts, etc. I basically dump anything in it that helps me work on the project.

    • Welcome, Jeni, and thanks for your comment!

      It sounds like your style guide pursues a similar idea, yet casts a much wider net by including processes, etc.

      To echo Marie’s concern, usability may become a problem sometime in the future. If the style guide ever gets too long or seems to address too many different groups of readers (printers, reviewers, developers), then maybe consider splitting it up?

  3. (a) Jeni: it looks like you are writing the Style Guide for yourself

    (b) Kai: you are “… drafting a style guide for documentation which now prepares the way for topics.” You may be interested in having a look at
    _The DITA Style Guide – A guide for Authors_ written by Tony Self []

  4. You have raised the role of a Style Guide beyond the writing conventions and guidelines. We have our style guide for conventions, standards and documentation practices, as well as for documentation plan and document structure. For example, what are the key elements that we should always (as far as possible unless the client strictly says NO) have in a document, what should be the default structure of an installation manual, and so on.
    It helps us stay consistent with our thought-process, specifically at the initial stage of a project.

    • Thanks, Vinish, for sharing your practices. We also findd that our style guide is a good source to complement our documented processes of drafting, writing and editing procedures, though we have those “how to” documents separate at the moment.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: