Imagine that your team of InfoDevs is involved into a large-scale legacy documentation project in which all best practices of writing are smashed up: the styles are misused, the document is inconsistent, the topics are long and complex, and it seems impossible to find any writing style in that mess. So, what can be done to breathe life into this project?
For sure, before updating the document and adding new content, the legacy document should be put into order. Consequently, the first step is to develop a documentation style guide.
What is a documentation style guide?
Generally speaking, the documentation style guide has much in common with general project style guide. Both of them cover the rules that a team should follow when developing a project; however, the documentation style guide covers just what involves documents.
Do I need a style guide if I follow a technical publication style manual?
There are several powerful arguments that can persuade you to create a style guide for your project. First of all, for some reasons you almost never follow the principles of a technical publication style manual for 100%. And in your style guide, you describe all norms and project peculiarities that a documentation team should be aware of.
Another argument is that no technical publication style manual will cover all peculiarities that your project may have. This means that to ensure that your document is consistent and looks professional, you will be obliged to introduce additional rules for documenting a project.
If documentation is developed by several InfoDevs, a style guide may ensure consistency within documentation, as every member of the documentation team will follow the same rules.
Finally, even if you are the only InfoDev on a project, you cannot dispense with a documentation style guide. Be professional! Use it as a knowledge base where you can get answers to any documentation-related issues in case you have forgot something. Moreover, you never know how rapidly your project will develop. In some time, the team may grow and you will need to use your documentation style guide for coaching new InfoDevs on your project.
When and how a style guide would bring value to my project?
A style guide is essential for every documentation project. First of all, it ensures consistency of the documentation where several InfoDevs are involved. Secondly, it facilitates knowledge transfer when new team members join a project. And finally, it allows us to work more efficiently and therefore, deliver quality documentation, because it is a knowledge base that is accessible for all team members any time they need it.
What should I include into a style guide?
There is no strict outline of what should be included into a documentation style guide. Its structure may vary from project to project depending on what type of documentation is developed. The only rule when creating a style guide is to make it exhaustive. In other words, try to cover everything that may cause some questions, discrepancies, or inconsistencies, and don’t forget about examples.
To be sure that you create a worthy style guide that covers every aspect of documenting a project, hold a brainstorming session with the team of InfoDevs who are involved into the project, and let everyone speak out.
If you are the only InfoDev on the project, create a list of key elements to be included into the style guide. You may think about covering the following items:
Provide the list of publication style manuals and other references that you follow when developing documentation on this project. This section may include the list of dictionaries, grammars, industry-specific style guides, and more.
A usage dictionary is the most important section of a style guide, because you won’t find how to use project-specific vocabulary in any publication style manual. A glossary of project terms should help InfoDevs decide which term to use in a particular context.
The usage dictionary may include any parts of speech. The only important thing is that it covers product and module names, user roles, program-specific terms and verbs.
For example, see a part of a project usage dictionary showed below.
|Term||Part of speech||Usage||Avoid||Example|
|action||n.||AVOID. See event||NA||NA|
|administrator||n.||Person who has all privileges within a system and who administers the system.||Do not use as synonyms: user with administrator rights, system administrator.||The administrator can define a specific period of time after which your password will expire.|
|event||n.||Employee activity.||Do not use as synonyms: task, action.||You may need to copy events when creating a new or editing an existing product.|
|execute||v.||Use to describe an action of generating a report.||Do not use as synonyms: run, generate, initialize.||The report will be executed with one of the following statuses: Success, Partial, or Failed.|
|MyPortal||n.||Employee’s part of the RS application.||NA||You can navigate between the MyPortal pages using the application menu.|
This sample includes the terms and their part of speech, shows how each term should be used, as well as provides words that should not be used as synonyms. And examples are the most important in the usage dictionary because they show the usage of every word in the context.
Grammar and punctuation
Documentation style guide should cover each case when you depart from the rules of publication style manuals. Grammar and punctuation rules are not exceptions. So, to be on the safe side, define the following:
- Voice and tenses to be used.
- Punctuation rules.
- Conventions foe writing abstracts:
- Define what type of information can be included.
- Define approximate length.
- Specify whether you include references.
- Conventions foe writing procedures:
- Specify whether it is obligatory that every procedure has a procedure heading.
- Define how to format one-step procedures.
- Define how to note optional steps.
- Specify whether you include graphics in procedures.
- Topic naming rules:
- Sentence-style capitalization vs. title-style capitalization.
- Bare infinitive vs. gerund.
Consistent usage of high-quality graphics can make your document look more professional. So, to be sure that every InfoDev in your team sticks to the same rules, specify graphics usage and placement rules. For example, define graphics file formats, size of images in the document, frame color and width, callouts, and any other elements that you use.
If you use any custom graphics or infographics, you may even think about including several samples of graphics into the style guide.
Text formatting conventions
On large documentation projects, it may not be enough to have a good documentation template or a style sheet. For a new documentation team member, it may be not obvious which style should be applied to which part of text. So, to be sure that every piece of content is formatted appropriately, you can add text formatting rules to your style guide. For example, you may specify which styles should be used for formatting UI elements, references, procedure headings, code elements, notes, warnings, lists, abstracts, and more.
File naming conventions
From the very project beginning, it is important to establish conventions for naming files and organizing the project structure on your computer or a server. This will ensure order within the project. And as your project grows, you and your colleagues will have no problems finding the necessary information.
Documentation process specifics
It is a good idea to cover a documentation development life cycle in a documentation style guide. First of all, this will ensure that all necessary documentation workflows are followed (including gathering information, interviewing SMEs, developing content, proofreading, implementing comments, publishing, and others). Moreover, this will allow all documentation team members to plan their time and work more effectively.
Creating a documentation style guide is not the end of the story. What makes a style guide a good one is timeliness. Like any other document, a style guide should be always updated according to new project requirements, UI changes, as well as modern design and writing trends. So, make sure that your style guide is always up to date, keep it your primary reference book and the result is not slow to arrive.
If this article has spurred you into creating a documentation style guide for your project, you may also be interested in exploring some samples. Below, I listed several style guides that may be interesting for you:
- Mozilla Developer Network (MDN) Writing Style Guide
- SUSE Documentation Style Guide
- Riak Documentation Style Guide
- Eclipse Doc Style Guide