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.