Style guides – an example and the debate continued
Style guides are a popular topic of late. I’ve just written a style guide for our new developer documentation site. The audience is both internal (Atlassian developers and technical writers) and external (community developers and authors). I wanted to create something useful and concise. Something developers will read.😉 Does it work?
The new style guide starts with a dot point summary. Here it is:
Style guide in brief:
- Ensure a maximum image width of 700 pixels.
- Use the theme colours and Zen Foundation macros for sophisticated effects.
- Include the product version to which your update is relevant. Use ‘Available‘, ‘Changed‘ and ‘Deprecated‘.
- Use plenty of code samples.
- Make use of our templates.
- Mark all drafts clearly as work in progress.
- Do not delete, move or rename any page that you did not create yourself.
- Use internal link format rather than the full [http://xxxx] external link format.
- Be aware that the content of some pages is reused in other pages. Make sure you put your content in the right place. This applies in particular to the Atlassian Plugin Framework documentation.
- Maintain a consistent style, layout, grammar and format with the rest of the page or space.
- Use Australian spelling. For example, use ‘organisation’ not
organization. Use ‘customising’ not customizing.
- Use title case for headings, not sentence case. For example, ‘This is a Heading’.
The rest of the page consists of a number of sections giving more detail about the dot points. Each section is itself concise. Where useful, I’ve included examples and illustrations.
All on one page?
We technical writers are asking ourselves all sorts of questions about style guides. Are style guides useful? Are they worth the effort? What should they look like? Do they curb creativity? Andrew Lui recently started a discussion on Technical Writing World, called Does your team use a style guide, which provoked some excellent responses.
Here’s my 2c. Yes, a style guide is useful and worth the effort, if it:
- Is descriptive rather than prescriptive. (But there are some industries that require prescriptive rules for legislative or compliance reasons.)
- Gives useful information that people would otherwise have to research and try out themselves. Examples are image sizes, colour codes and fonts that work.
- Is lightweight and easy to read.
- Suits the structure and requirements of the team of writers.
- Satisfies the requirements of the organisation.
- Is open to change.
If the organisation prioritises fast documentation delivery and agile response to changing requirements over consistency, and if the team of technical writers is small, then maintaining and ensuring adherence to a style guide may present too much overhead.
My example style guide is nowhere near perfect. It is, and always will be, a work in progress. But it suits our needs at this time.
Any other examples and thoughts?
Do style guides stifle creativity and innovation? I think the answer is: “Not necessarily”. A good style guide gives you a framework within which to be creative. A good style guide is also flexible enough to incorporate change. Kai Weber wrote a post about a related topic recently, creativity and structured writing. People added some interesting comments there too. Let me know what you think about style guides, and drop a link if you have seen a good one or a good blog post about them recently.🙂