I was fortunate enough to be able to speak about what I love at the Write The Docs Australia conference this week. Today's post will tell you about my subject matter: style guides.
Note: This is a long post that covers the entirety of my presentation material.
Note: This is a long post that covers the entirety of my presentation material.
Background
My background for a number of years was in copyediting, working with training materials for vocational education.
Two years ago, I transitioned into technical writing with an information security consultancy. The material I deal with is heavily IT focused, and needs to be understandable by professionals ranging from the IT technician on the ground, all the way up to C-suite execs who may only know enough about computers to fire up email or their excel spreadsheet.
The majority of my experience consists of quality assurance, editing material written by others so that the people receiving the documentation are more able to understand the text. The style guide is one of the most important documents in this process.
Two years ago, I transitioned into technical writing with an information security consultancy. The material I deal with is heavily IT focused, and needs to be understandable by professionals ranging from the IT technician on the ground, all the way up to C-suite execs who may only know enough about computers to fire up email or their excel spreadsheet.
The majority of my experience consists of quality assurance, editing material written by others so that the people receiving the documentation are more able to understand the text. The style guide is one of the most important documents in this process.
Some language
- Style sheet
- Style guide
- Style manual
A style sheet is a quick way of noting style choices as you make your way through a document, so that you can keep internal consistency. I generally use a piece of notepaper because I like the tactile flow of it, but you may prefer a spreadsheet or a word document. I generally use a style sheet for each new document I deal with.
A style manual is quite a lot larger than a style sheet. It will provide comprehensive instructions that cover language, punctuation, layout, heading use, referencing, etc.
I personally prefer Snooks and Co Style Manual, which has extensive uptake throughout Australia. If your target audience is in the US, there are other good style manuals available. I highly recommend the Chicago Manual of Style, which includes everything I could ever want from a style guide.
You can also access some style manuals online, such as the Apple Style Guide or the Microsoft Writing Style Guide, which replaced the Microsoft Manual of Style early this year.
A style guide sits somewhere in between a style sheet and a style manual. It's used by a team to ensure that everyone is writing using the same words, tone, and punctuation. This is what I'll be focusing on.
Why Art?
In the title, I called this the art of consistency, so why is it an art?
I'm a poet. My first love was poetry, and it's the foundation of what I do. And the underlying message of poetry is that structure and consistency create harmony in the mind of a reader.
Your writing choices affect the way a reader perceives you. Whether you choose to include a 'u' in colour or honour, or use a z in words like sympathise, or a serial comma at the end of a list, all build a picture in the mind of a reader, and can signal cultural sameness with your target audience.
So, as an organisation, by creating a unified approach to spelling, punctuation, and other points where differences may creep in, you can build documentation that reduces dissonance in the eyes of the reader.
I'm a poet. My first love was poetry, and it's the foundation of what I do. And the underlying message of poetry is that structure and consistency create harmony in the mind of a reader.
Your writing choices affect the way a reader perceives you. Whether you choose to include a 'u' in colour or honour, or use a z in words like sympathise, or a serial comma at the end of a list, all build a picture in the mind of a reader, and can signal cultural sameness with your target audience.
So, as an organisation, by creating a unified approach to spelling, punctuation, and other points where differences may creep in, you can build documentation that reduces dissonance in the eyes of the reader.
Why have a style guide?
So the question becomes, why have a style guide at all? We can just go and get a style manual and a dictionary.
The key to a style guide is usability. I want every person in my organisation to use the same style, and I know that they aren't going to be happy trawling through 600 pages of stuff. They're not really as into words as I am, and there's a bunch of stuff in the style manual that I really only need in extraordinary circumstances.
Plus perhaps we want to do things a little differently. Every organisation has slightly different needs, and a style guide will capture those points for you.
The key to a style guide is usability. I want every person in my organisation to use the same style, and I know that they aren't going to be happy trawling through 600 pages of stuff. They're not really as into words as I am, and there's a bunch of stuff in the style manual that I really only need in extraordinary circumstances.
Plus perhaps we want to do things a little differently. Every organisation has slightly different needs, and a style guide will capture those points for you.
Who is it for?
Having decided to create a style guide, who is it for? It's important that you know who is going to be using your style guide. A style guide written for your marketing team may need to cover different points from one that is written purely for high-level technical consumption, for example.
This is going to affect the sorts of things you include, as well as who your stakeholders are.
This is going to affect the sorts of things you include, as well as who your stakeholders are.
Involve others
Your stakeholders are important to talk to.
Before you even get started on constructing your guide, talk to the people who will be using it. Find out what they need to know, what questions writers are coming up against, and what the common discrepancies are that are being found by your quality review or editorial staff. Writing a style guide from a vacuum is not going to get you the results you need.
You'll find, once you get started, that if one person identifies a need, you'll have a dozen others suddenly chime in “I wondered that as well...”
There's an added benefit to this, also. The more involvement people have in the style guide at this stage, the more uptake you'll have of it later. When people feel that they've contributed, they are more likely to feel ownership in the project.
I've found that the people I involve at the earliest stages of the style guide become almost like signal repeaters, so that it's no longer just me saying 'Go look at this document..'
Before you even get started on constructing your guide, talk to the people who will be using it. Find out what they need to know, what questions writers are coming up against, and what the common discrepancies are that are being found by your quality review or editorial staff. Writing a style guide from a vacuum is not going to get you the results you need.
You'll find, once you get started, that if one person identifies a need, you'll have a dozen others suddenly chime in “I wondered that as well...”
There's an added benefit to this, also. The more involvement people have in the style guide at this stage, the more uptake you'll have of it later. When people feel that they've contributed, they are more likely to feel ownership in the project.
I've found that the people I involve at the earliest stages of the style guide become almost like signal repeaters, so that it's no longer just me saying 'Go look at this document..'
Getting started
Remember back at the start I talked about a style sheet? This is where you start. Get a bunch of documents that your organisation has already pumped out, or that you're working on right now, and go through them one at a time. Make a style sheet for each one. Make sure you get the full breadth of documentation that you're writing for, so you can see everywhere that's going to ultimately be affected.
This is where using a spreadsheet instead of my initial piece of paper works really well, because you can make direct comparisons. You can have notation for more than one document at a time and see where your trends lie. If your team is making frequent choices of one sort or another, for example, using a specific citation method, capture that practice rather than changing it.
Describing what you do is generally better than making a new set of rules, because in training, in templating, and across the board, it costs less to implement.
This is where using a spreadsheet instead of my initial piece of paper works really well, because you can make direct comparisons. You can have notation for more than one document at a time and see where your trends lie. If your team is making frequent choices of one sort or another, for example, using a specific citation method, capture that practice rather than changing it.
Describing what you do is generally better than making a new set of rules, because in training, in templating, and across the board, it costs less to implement.
Formatting
Before we look at what to include in your style guide, I want to touch on formatting.
Welcome to anecdote time.
When I first made my way into editing, I started working for a company that had multiple business registrations, each running multiple brands, all working with the same documentation, but with different formatting for each brand. By the time I finished working for that company, the initial brands had been totally replaced, and more brands had been added.
This was very much a formative experience for me. There was a choice to be made early on - building a style guide for each brand was double handling, and building exceptions into the style guide for each brand would lead to it being clunky and confusing. The simplest way was to separate writing style and formatting style from each other.
Because of that experience, my practice has always been to separate out writing instruction from formatting and graphic elements.
If your writers and documentarians need to also worry about getting their colours and fonts right, I think you're probably doing it the hard way, because documentation templating is a wonderful thing.
Template as much as possible. If you have tools that can force template automation, that's even more of a win. If you find that you really need to include formatting, keep it as brief and simple as you can.
I will add an exception here. If you're trying to meet WCAG standards (that's web content accessibility guidelines for anyone who doesn't speak acronym), set out your expectations, especially for things like alt-text.
Welcome to anecdote time.
When I first made my way into editing, I started working for a company that had multiple business registrations, each running multiple brands, all working with the same documentation, but with different formatting for each brand. By the time I finished working for that company, the initial brands had been totally replaced, and more brands had been added.
This was very much a formative experience for me. There was a choice to be made early on - building a style guide for each brand was double handling, and building exceptions into the style guide for each brand would lead to it being clunky and confusing. The simplest way was to separate writing style and formatting style from each other.
Because of that experience, my practice has always been to separate out writing instruction from formatting and graphic elements.
If your writers and documentarians need to also worry about getting their colours and fonts right, I think you're probably doing it the hard way, because documentation templating is a wonderful thing.
Template as much as possible. If you have tools that can force template automation, that's even more of a win. If you find that you really need to include formatting, keep it as brief and simple as you can.
I will add an exception here. If you're trying to meet WCAG standards (that's web content accessibility guidelines for anyone who doesn't speak acronym), set out your expectations, especially for things like alt-text.
What should the style guide contain?
Now lets get down to some nitty gritty – what your style guide needs to contain.
These are certainly not the only things you're going to need to include, but these are the things I've found need the most clarification.
Title capitalisation is an argument I've had across three different style guides. There are two main schools of thought – Title case, where capitalisation is used in most words in the heading, and sentence case, where only the first word is capitalised.
Trends favour sentence case. I like sentence case. I think it's simpler.
Title case is hard. It's hard to define, everyone has their own variant ruleset, and it's confusing for the people implementing it. However, Baby boomers and Gen Xers were brought up with the idea that this is how titles should be, and they're the ones that often have final say. Also, if you're not defining this right at the beginning of your organisation's setup, it can be expensive to change. If you're looking at, for instance, a database of 1000 regular-use entries that each have a heading in title case, that's a lot of man hours to make a switch.
Your title capitalisation is also highly visible. If you don't add a ruleset into your styleguide for this, you'll find that people make their own rules and things will start to look messy.
American English vs British English.
This issue is often invisible until you have a single instance of one '-ize' on a page surrounded by '-ise', or vice versa.
You'll find that some people are more sensitive to spotting inconsistent dialectical spellings than others, and those people are often very vocal.
You may also require very granular rules around usage of American and British English, especially if you're working with documentation that includes code, as a lot of programming field names use American spelling.
I learned this the hard way the first time I edited an IT text, when I used find/replace all and had authors yelling at me for about a month.
It's helpful to also add a preferred dictionary into your style manual, and tell people to default to the first instance of spelling in the dictionary for edge cases.
Serial Commas! These are also called Oxford Commas.
So many people don't use these, and they should. There have been lawsuits raised and won over the lack of serial commas in contracts.
I like clarity. I don't think I've ever seen ambiguity arising from including a serial comma, but I've certainly seen it happen from failing to use one.
Bullet lists.
I know I am broadly generalising here, but nobody knows how to punctuate bullet lists. This includes the colon leading into the list, the consistency of grammar inside the list, and the punctuation at the end of each bullet point.
These are really important for setting tone. The level of formality in your bullet point punctuation can change the way your readers perceive the material they're reading. For example, using a semi-colon at the end of each dot point may look old-fashioned in some contexts, but can add an authoritative air, where a lack of punctuation in dot points may seem less formal and more personable.
Numerals vs spelled out numbers.
It seems easy to just say, "Write our numbers one through nine..."
And then suddenly you have hard data and that's no longer applicable. Giving hard rulesets in your style guide makes this an easier choice for your writers to make.
Time and Date.
These are certainly not the only things you're going to need to include, but these are the things I've found need the most clarification.
Title capitalisation is an argument I've had across three different style guides. There are two main schools of thought – Title case, where capitalisation is used in most words in the heading, and sentence case, where only the first word is capitalised.
Trends favour sentence case. I like sentence case. I think it's simpler.
Title case is hard. It's hard to define, everyone has their own variant ruleset, and it's confusing for the people implementing it. However, Baby boomers and Gen Xers were brought up with the idea that this is how titles should be, and they're the ones that often have final say. Also, if you're not defining this right at the beginning of your organisation's setup, it can be expensive to change. If you're looking at, for instance, a database of 1000 regular-use entries that each have a heading in title case, that's a lot of man hours to make a switch.
Your title capitalisation is also highly visible. If you don't add a ruleset into your styleguide for this, you'll find that people make their own rules and things will start to look messy.
American English vs British English.
This issue is often invisible until you have a single instance of one '-ize' on a page surrounded by '-ise', or vice versa.
You'll find that some people are more sensitive to spotting inconsistent dialectical spellings than others, and those people are often very vocal.
You may also require very granular rules around usage of American and British English, especially if you're working with documentation that includes code, as a lot of programming field names use American spelling.
I learned this the hard way the first time I edited an IT text, when I used find/replace all and had authors yelling at me for about a month.
It's helpful to also add a preferred dictionary into your style manual, and tell people to default to the first instance of spelling in the dictionary for edge cases.
Serial Commas! These are also called Oxford Commas.
So many people don't use these, and they should. There have been lawsuits raised and won over the lack of serial commas in contracts.
I like clarity. I don't think I've ever seen ambiguity arising from including a serial comma, but I've certainly seen it happen from failing to use one.
Bullet lists.
I know I am broadly generalising here, but nobody knows how to punctuate bullet lists. This includes the colon leading into the list, the consistency of grammar inside the list, and the punctuation at the end of each bullet point.
These are really important for setting tone. The level of formality in your bullet point punctuation can change the way your readers perceive the material they're reading. For example, using a semi-colon at the end of each dot point may look old-fashioned in some contexts, but can add an authoritative air, where a lack of punctuation in dot points may seem less formal and more personable.
Numerals vs spelled out numbers.
It seems easy to just say, "Write our numbers one through nine..."
And then suddenly you have hard data and that's no longer applicable. Giving hard rulesets in your style guide makes this an easier choice for your writers to make.
Time and Date.
This is quite important in some contexts. Consider the image to the right titled Ambiguous time notation for just a second.
Picking a notation, making it consistent, and adding context can make a large amount of difference to the meaning. The image to the right titled Unambiguous time notation gives a lot more context to the reader, there is no ambiguity. This isn't the only way you can write unambiguous times. There are a number of standards online that you can refer to. This is especially important for audit trails, but can also affect things like logging time for HR and accounting purposes. |
Gender.
I wish we could all put this to bed, but I came across this one very recently. A writer I hadn't worked with before referred to programmers as 'he' multiple times per page throughout a 50 page document.
That's going to be highly visible to any woman that reads it. You'll also find the same issue in reverse if you switch he to she, and if you alternate the two, it's going to be jarring for every reader.
And, of course, there are still those that rale against the use of singular they, despite it being in use since the 14th century. I wish they'd catch up with the times.
Non-breaking characters.
The reader doesn't see them so they shouldn't matter, right? They're just there to make text flow nicer on the page.
That is, until someone comes to an ugly URL that's breaking in a weird place, so that someone fixes it by replacing a dash with a non-breaking hyphen.
The key here is that non-breaking characters have different unicode from their standard counterparts, so the moment someone goes to copy/paste the URL, they find that the link doesn't work. This may not be apparent to a lot of people, so rules need to be defined, and if you decide to rule against these characters in some situations, it may also help with adoption to include a brief explanation on why.
Spacing after a full stop.
This is one of those issues that is broadly generational. If you learned to type on a typewriter rather than on a computer, you probably learned double-spacing after a sentence.
Some people think that double spacing after a sentence makes text look gappy, so frown on the practice. It really makes no practical difference one way or the other.
However, this is an issue if you have multiple authors on a single document, where the inconsistent spacing will become noticeable and possibly distracting.
Passive vs Active voice.
I blame Microsoft for this one. Before the introduction of Clippy in Word, nobody thought passive voice was an issue.
I wish we could all put this to bed, but I came across this one very recently. A writer I hadn't worked with before referred to programmers as 'he' multiple times per page throughout a 50 page document.
That's going to be highly visible to any woman that reads it. You'll also find the same issue in reverse if you switch he to she, and if you alternate the two, it's going to be jarring for every reader.
And, of course, there are still those that rale against the use of singular they, despite it being in use since the 14th century. I wish they'd catch up with the times.
Non-breaking characters.
The reader doesn't see them so they shouldn't matter, right? They're just there to make text flow nicer on the page.
That is, until someone comes to an ugly URL that's breaking in a weird place, so that someone fixes it by replacing a dash with a non-breaking hyphen.
The key here is that non-breaking characters have different unicode from their standard counterparts, so the moment someone goes to copy/paste the URL, they find that the link doesn't work. This may not be apparent to a lot of people, so rules need to be defined, and if you decide to rule against these characters in some situations, it may also help with adoption to include a brief explanation on why.
Spacing after a full stop.
This is one of those issues that is broadly generational. If you learned to type on a typewriter rather than on a computer, you probably learned double-spacing after a sentence.
Some people think that double spacing after a sentence makes text look gappy, so frown on the practice. It really makes no practical difference one way or the other.
However, this is an issue if you have multiple authors on a single document, where the inconsistent spacing will become noticeable and possibly distracting.
Passive vs Active voice.
I blame Microsoft for this one. Before the introduction of Clippy in Word, nobody thought passive voice was an issue.
The work I do often involves telling people how they can improve what they do. Passive voice is vital for this. Because while saying 'The IT system had no security controls' is functionally the same as saying 'We found that security controls were not present on the system,' the people on the receiving end may feel that the active voice is too aggressive. Passive voice is frequent in auditing and scientific writing, where text may need to be more objective. Moreover, if your team writes a lot in one voice, a sudden switch to the other may be jarring to the reader. |
Do you deal with odd spelling?
I do. The bolded items in the next paragraph look like typos, but they aren't.
Referer header is a computing field name that identifies the address of a web site when you click a link. It was a typo in 1996, but now it's an actual word due to the Internet. And Requestor (or rather than er) is used frequently in programming.
You will probably have totally different instances of oddly spelled words. Words like these need clarification on when to use them as well as how to spell them.
Camel Casing...
...is the practice of creating words or acronyms with a combination of capital and lower case letters. It's named camel casing because the pattern makes humps in the word. The most familiar of these is probably iPhone or FedEx, but camel casing is used frequently in IT contexts, such as in LaTeX.
I do. The bolded items in the next paragraph look like typos, but they aren't.
Referer header is a computing field name that identifies the address of a web site when you click a link. It was a typo in 1996, but now it's an actual word due to the Internet. And Requestor (or rather than er) is used frequently in programming.
You will probably have totally different instances of oddly spelled words. Words like these need clarification on when to use them as well as how to spell them.
Camel Casing...
...is the practice of creating words or acronyms with a combination of capital and lower case letters. It's named camel casing because the pattern makes humps in the word. The most familiar of these is probably iPhone or FedEx, but camel casing is used frequently in IT contexts, such as in LaTeX.
What should you leave out?
Don't put procedure into your style guide, or process, or policy. If you have version control requirements, those are procedure. If you have structuring requirements for certain types of content, those are also procedure. It's tempting, because it's a place everyone's supposed to be looking at all the time, but it will bloat the body of your document and less people will refer to it.
Similarly, don't add large amounts of writing instruction. If you find it's necessary to reteach written language to your document authors, this is better done in other formats.
If you've got a wiki or a knowledge management system that's accessible to all, perhaps set up a specific section for writing resources so that staff can pick and choose the content they need, but keep your style guide lean.
Similarly, don't add large amounts of writing instruction. If you find it's necessary to reteach written language to your document authors, this is better done in other formats.
If you've got a wiki or a knowledge management system that's accessible to all, perhaps set up a specific section for writing resources so that staff can pick and choose the content they need, but keep your style guide lean.
How long should a style guide be?
When I say lean, how long do I mean?
I did a little bit of research before putting all of my information together, and there are a lot of thoughts on how long to make your style guide. Some say no more than four pages. Some say no more than 10.
I have a general belief that a style guide should be as long as it needs to be and as short as possible.
Too long and nobody will read it, and if they do read it, they won't remember it.
I did a little bit of research before putting all of my information together, and there are a lot of thoughts on how long to make your style guide. Some say no more than four pages. Some say no more than 10.
I have a general belief that a style guide should be as long as it needs to be and as short as possible.
Too long and nobody will read it, and if they do read it, they won't remember it.
Communication
Before we finish up, there's one more point to cover. Getting buy in. Because your document's not useful if nobody knows it exists.
If you consulted with people at the start of your process, they know it's coming. So when you finish your style guide, or at least get its first incarnation to a readable point, tell people.
Make sure it's in a place people can access it freely.
Treat it like a policy and send out an organisation-wide email.
Provide training in its use. This is an efficient way of getting it into lots of people's heads all at the same time
Work it into other internal writing-related content. Link to it as much as possible to get that consistent message across.
Add it into your document quality assurance procedures.
And because new employees need to know about this wonderful thing and osmosis is slow, make it a part of your first week onboarding process, especially if documentation is a large part of the role.
If you consulted with people at the start of your process, they know it's coming. So when you finish your style guide, or at least get its first incarnation to a readable point, tell people.
Make sure it's in a place people can access it freely.
Treat it like a policy and send out an organisation-wide email.
Provide training in its use. This is an efficient way of getting it into lots of people's heads all at the same time
Work it into other internal writing-related content. Link to it as much as possible to get that consistent message across.
Add it into your document quality assurance procedures.
And because new employees need to know about this wonderful thing and osmosis is slow, make it a part of your first week onboarding process, especially if documentation is a large part of the role.