How to write a style guide (that people can actually use)

Scroll asked me to write a style guide for That’s the website for the Health Service Executive in Ireland.

Awesome job, I thought. Who doesn’t love a style guide? And I set out to write the best damn style guide known to humankind.

Turns out, that’s quite hard.

What is a good style guide?

I’ve known a lot of style guides in my career. But when I sat down to think about it, not many of these were all that great.

In fact, quite a few were pretty interchangeable.

So, what was good about the good ones? I eventually came up with 3 characteristics that a good style guide should have:

  1. relevant – not generic
  2. usable – not just good on the shelf
  3. empowering – give me a mandate

1. Relevant not generic

Style guides work if they are specific to the digital brand. They should help content designers answer questions that they will encounter every day when they work on their content. (So, recycling the Guardian style guide just won’t cut it.)

Diagnose the problems first

To make HSE’s style guide relevant, I immersed myself in their content. I ran content audits for quality and to work out common problems.

Offer the right tools in the style guide

Once I had diagnosed common problems, I knew what tools the team needed.

For example, there was inconsistent use of terms like ‘doctor’, ‘GP’ and ‘health practitioner’. I checked the analytics and now the correct term is ‘GP’ and that’s in the A-Z.

There was also inconsistency in things like contact details, and warnings in health content. Content design patterns are the best way to fix that problem, so we created a set of those.

Then I developed sets of hard rules for language and structure. Following these should help the team crack down on badly structured pages and an occasional tendency to wordiness and jargon.

Don’t reinvent the wheel

None of this reinvents the wheel – rules for structure are rules for structure, and you can find my rules in any decent style guide. But I took a lot of care to focus on the rules that would really make a difference to HSE’s content, specifically.

2. Usable, not nice on the shelf

Not too long. Not preachy. Not wildly Utopian. Not vague. Something I’ll use every day because it works.

Know what to focus on

Once I felt I knew the problems on the site, I knew what to focus on and what to cut. The HSE style guide has a lot to say about bullets and titles and page structure and user need.

It doesn’t bang on about where to put the full stop when you use brackets.

(It’s still too long, though.)

Utopian, but not wildly

In an ideal world, we would research and user-test and design every piece of content to the nth degree. But we’re in the real world. So, I gave shortcuts wherever I could, like how to get data in 10 minutes.

Check people can use it – and iterate

I still needed to know that the style guide was actually usable – that HSE’s content team could apply it to their work.

So I ran review workshops with the content team where we checked content against the style guide. This showed me where the style guide wasn’t clear or prescriptive enough, and I could iterate to fix these problems.

It also showed how following the style guide works – it creates better content.

Make sure people own it

Style guides need love, attention and ownership to stop them from becoming the cranky document gathering dust on the shelf.

We tried to find ways to stop this happening. At HSE, the style guide rotates through different owners. Everyone, including senior management, takes a turn at managing and updating it – being the style czar. HSE holds style council meetings to make sure it stays on everyone’s agenda.

3. Give me a mandate

HSE were clear that they wanted a style guide that said, “This is how we do things.” And that really resonated with me. The best style guides will give you the mandate. They will empower you to make and defend content design choices.

So I tried to write a set of content principles that define HSE’s content – how they design content and why. I included links to research that supports the principles and rules. (Sometimes, it’s not enough to say ‘Because it’s in the style guide’ – content designers need to know why we do what we do.)

This style guide is now the hill that HSE content designers can die on.

What worked well

  •    Hours spent diagnosing HSE’s content problems
  •    Providing tools to fix those specific problems
  •    Lots of communication with the HSE manager in charge of the project
  •    Several rounds of feedback from the wider HSE team
  •    The review workshops where we applied the style guide and checked it was usable

What I’d do differently next time


All these rules work better if you have clear examples (good and bad) to illustrate them. But finding representative examples on HSE’s site was time-consuming and sometimes contentious.

If I’d known how long this would take, I would have been more careful about recording these when I first reviewed the content, instead of trying to find them retrospectively.

Ditto content design patterns, actually.

The A-Z

The A-Z of common terms and spellings was also difficult and time-consuming. This really needs to be developed by the content teams, working with medical subject matter experts. I knew this but should have been better at setting this expectation.

Read what HSE said about Scroll’s work in our case study.