Recently, I was tasked with creating a style guide for our documentation department. As a bit of a perfectionist and a stickler for grammar, punctuation, and consistency, I was (not so) secretly excited to take charge of this project. Our documentation was a mess, and our team was growing. A style guide was in order!
Why create a style guide
I work for a company that started in 2001 with 6 employees, and the documentation department was formed along the way as the company grew. The team comprised a mix of employees with varying backgrounds, none of them in technical communication. And - sorry guys - it showed in our documentation. Our Administrator’s Guide is over four hundred pages of rambling text with differing styles of punctuation, grammar, and diction on almost every page.
Enter the style guide. Among its many functions, the style guide does the following:
- Keeps everyone writing consistently
- Defines formatting for items like bulleted lists (like this one!)
- Provides guidelines and allows new employees to get up to speed without having to sift through our existing documentation
- Creates an avenue for writers to bring up issues for discussion with the team
How to create a style guide
For our style guide, I relied on the fourth version of the Microsoft Manual of Style. I started by identifying the biggest pain points in our documentation. For us, these included general style and voice considerations (most of this hadn’t been touched since it was first created years ago, so we had lots of very formal, antiquated language), the formatting of procedures and technical content, and user interface considerations.
I focused on what Microsoft had to say about these areas and created a basic guide that covered these issues. I also added a section for miscellaneous style decisions, such as numbers, acronyms, and screenshots. The usage dictionary section rounded things out, and our style guide was created.
Implementing style decisions
While the style guide itself is important, implementation by the team is totally crucial. The following items have made this easier for our team.
- Wiki development - using a wiki to create the style guide has given us a dynamic, living document, enabling real-time interaction and easy access to this information for each team member
- Team meetings to discuss decisions - it was really helpful for us to meet as a team to make sure everyone understood the style decisions and the way to proceed
- Forum for submitting changes, requests, or things to talk about in future - for us, this is simply a wiki page where any member of the team can add ideas or requests for the team to discuss and decide on
We’re nowhere near perfect yet, and there is still a huge amount of work to do. But the style guide is an invaluable tool and makes doing our jobs more straightforward and seamless.
Don’t have a style guide yet? Create one!