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:

The details

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?

Yes.  😀

The debate

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. 🙂


About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 15 October 2011, in technical writing and tagged , , , . Bookmark the permalink. 16 Comments.

  1. One page! I like it! I do believe in style guides. It’s the right place to put those little things that you only deal with once in a blue moon that still need to be consistent. It’s also perfect for locking down certain house rules like spelling or voice. I don’t believe in having explanations of effect vs affect, however. That is information that you can find in your style guide’s “foundation” such as Chicago Manual of Style, Microsoft Manual of Style, or Read Me First.

    • Hallo Karen

      It’s great to “see” you again. 🙂 I’m not sure what you mean about explanations of affect vs effect. Maybe that the style guide shouldn’t go to the level of detail of explaining the difference between those two words?

      I agree that there should be a good solid style guide behind the scenes. Being situated way down here in the antipodes, we use some Ozzie style guides that are mentioned at the bottom of the online guide. For technical writers and other such intrepid souls.


      • Re: effect vs. affect. I was a bit too brief there! I think your style guide needs to list things like how to display your logo, what voice do you use, what is the typeface, etc. You don’t need grammar rules like what’s the difference between effect and affect. SMEs and others will make their mistakes. Some love to learn from you, so you send them to good grammar sites or you share your books with that info. Deal with those problems when they appear, but don’t detail that information in your style guide. That can lead to bloat. Only list the really pertinent info – just as you have done here.
        I hope that’s better!

  2. I like this. The 30-year technical writer in me wants to see more rules than this. But the realist in me concedes that adding more rules merely increases the likelihood they’ll never be read. Perhaps a compromise would be, as Karen suggested, to cite one of the popular style guides — Chicago, AP, or Microsoft — as a way to ensure consistency in matters like the serial comma or whether to use “select” or “click.”

    Can you help me understand, please, what you mean by “descriptive rather than prescriptive”? It seems like these rules, even though they leave a lot of room in which to be creative, are still prescribing one set of behaviors over another. Thanks.

    • Hallo again Larry 🙂

      Totally agreed that there should be an authoritative style guide backing up the short online version. We do mention ours, right at the bottom of the page. Being based in Australia, our style reference is the Style manual for authors, editors and printers, sixth edition, published by John Wiley & Sons Australia, Ltd. Our reference dictionary is: Macquarie Essential Dictionary, fourth edition, published by Macquarie Dictionary Publishers at the University of Sydney.

      Good question! By “descriptive rather than prescriptive”, I mean that we’re describing the best way to do things. If people find a better way, they are free to use it. We’ll see it and maybe change the style guide. So in that sense, it’s not prescriptive, in that it’s not an attempt to impose a rule of correct usage. On seeing your question, I did a bit of research and saw that the term “prescriptive” can be used in two ways. Interesting, and perhaps a difference between UK and US usage.The first definition in this online dictionary is the one I’m more used to:


  3. +1 on selecting CMoS, MMoS or similar as the background/shadow style guide. We’ve selected MMoS for that purpose and regulated a few deviations and some special in-house style guidelines (on too many pages, I’m afraid…).

    Oh, by the way, a new edition of the Microsoft Manual of Style is scheduled for November.

  4. Sarah,

    Style guides work fine as a dispute settlement mechanism, in which role they can be as big as you like, because they are only consulted when a specific doubt or dispute arises. By quickly settling doubts and disputes, the style guide can improve productivity. In this role, a big style guide is better because it will cover more of the doubts or disputes that may arise.

    But your content is never going to fully comply with such a style guide, because no one can hold it in their heads. If you want a full and universal compliance with a style guide, it had better be short, otherwise, style auditing is going to kill productivity.

    So really, I think, there is room for two things: non-prescriptive style guidance (as comprehensive as possible) and prescriptive style requirements (as brief as possible). The prescriptive requirement should be directly tied to identifiable business requirement (that is, they should demonstrably affect revenue). If they don’t affect revenue, they are pure cost: money out the window.

    A couple of points about your specific guide:

    * Three of the points are process, not style issues. Mixing process with style is generally a bad idea.

    * There are lot of things here which, if I were doing this for a structured writing environment, I would either remove from the style guide and implement in code, or I would write audit scripts to check. This is a markup system. Being wiki markup, it is not as rigorous as XML, and you may have less opportunity to move style issues to code. But wiki markup should be structured enough that you could do automated style auditing on it. That would help reduce the amount of guidance you have to give and would help people learn to do the right thing.

    • Hallo Mark

      Wow, thanks for the information-packed comment! I really like your summary of the two types of style guides and the reasons for each. Excellent.

      Yes, our guide is a bit of a mish mash. That’s because I wanted to put all the important guidelines into it, regardless of whether they’re typographical, stylistic or procedural. Perhaps I should change the name of the guide. In fact, there’s another guide called “how to edit …” which is entirely procedural. The division between the two guides is that people really need to read the “how to edit” guide, or they just won’t be able to do anything. They’re unlikely even to find the edit button, which is strange in a wiki. Having read the “how to”, then can mosey along to the style guide for more information.

      I love your idea of writing audit scripts to check some of the style items on a page. Definitely worth investigating!


  5. Can you explain the decision behind using Australian spelling? I know that Atlassian is an Australian company, but I am used to companies deciding to use US or UK English depending on where their biggest customer market is. I assume your biggest customer base is not Australia?

    • Hallo Nicole

      Ah, thereby hangs a tale! You are quite right, our biggest customer base is in the US. We decided to use Australian spelling a while ago, on both the company website and the documentation site, because it added to the character of the company. People know us as “that company from Australia”.

      Recently, in the past year or so, we have made the decision to use US spelling on the website. It’s possible that the docs will follow suit. We already have some weirdnesses in the docs. For example, we strive to use “license” throughout, even where it should be “licence” according to the Australian dictionary.

      Cheers, Sarah

    • We also use Australian spelling, primarily because the UI is in Australian English. We can’t have “Cheque” in the UI, and talk about checks when referring to such elements. We might change in the future, but it will be as and if a whole product set changes to American English.

  6. Oh, another point inspired by Mark’s very useful comment. Another great purpose for style guides is helping new employees. When you start a new job it is so helpful to have a guide to get you started on the right track. I have been at companies with no style guides, and I have made them to help myself remember my own decisions and to have something to show a new colleague or a consultant. I have been a companies where there was no writer, but where there had been someone – a someone who made a style guide. In one particular place, I was so grateful for this. She had documented many procedures that were a huge help to me, especially because no one really knew how to do them. Being a technical writer, she had done an excellent job of writing them, too.

    • Hallo again Karen
      That’s a great point. On our intranet, we have a fairly large collection of guidelines concerning various procedures and techniques to do with writing, publishing and managing the documentation. They’re quite fluid and flexible, and we all update them continuously as things change. They’re very much an in-depth guide for technical writers. Getting down to the nitty gritty, with tips for handling specific problems and the oddities of specific documentation sets. When I first arrived at the company, there was only one other technical writer, so we didn’t need much. But as the team has expanded, so have the guidelines. They’re invaluable for new team members.

  7. Hi Sarah, since a lot of what a Tech Pubs department’s style guide needs to cover is already covered by existing authoritative, commercially published style guides, I would more explicitly and specifically refer you reader to those sources. (For instance, “title case” is not a broadly accepted notion as to its details.) As an intro to your style guide, I recommend identifying what are the key areas of guidance your style guide addresses and relate those areas to what is found in your team’s preferred commercial guide(s)–that is, cite the sections of the commercial guide that you expect the reader to be/come familiar with. That way, the rest of your style guide is a set of guidance that represents additions to, subtractions from, or revisions to what’s found in your preferred commercial guide(s).

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

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: