Docs are (sad to say) often a point of last resort for a reader who’s already frustrated and cranky over failing to figure out the answer through trial and error, so any additional barriers to them getting at the information they need will not go down well. If more than one person writes your documentation, a style guide is a must to ensure that your end reader feels comfortable with and confident in your documentation.

A common voice and consistent approach to presenting information sets expectations, and hopefully inspires confidence. An obvious mashup of sections written in different styles and to differing standards with no consistency or sense of continuity, on the other hand, will frustrate and annoy.

So how do I achieve a common voice, and so on?

A well-defined style guide should allow multiple contributors to add to a document while giving the impression it’s been written by a single author by answering all stylistic questions for the document. Ideally, a style guide should define both the particulars of language usage, and how information is to presented, structurally and visually.

Example structural questions

• Will we use sections as well as chapters? If so, will there be a section overview as well as chapter overviews?
• Will chapters always include an example case study in their overview?
• Will there be a recap at the end of a chapter?
• Will reference tables describing field properties be included mid-chapter, or in a dedicated chapter section or an appendix? (“The value in this field must be a percentage, expressed as a 4 digit decimal number between 0.000 and 1.000. When you click Save, the value in the Loan Amount field is multiplied by this percentage and the calculated value is displayed in the Interest field.”)
• Will instructions be titled, and if so how? (“How to format text”, “Formatting text”, “To format text:”, …)
• Will instructions include illustrative cropped screenshots inline, or refer back to a single screenshot with numbered callouts?
• Will tables be numbered? Will they be cross referenced by number, title, page or a combination of all three?
• Will there be appendices, or an index?

Example language questions

• How do we describe clicking through a menu structure? (“To do X, first click the A menu, and next click on the B option.” or “Click A > B to do X.”)
• What terminology do we use for screen elements? (Is it a menu, a drop-down, a drop-down menu, a selection field, …?)
• What terminology do we use for activities? (Do we click? Select? Tick? Choose?)
• Should we use active or passive voice in examples?
• Do we label sections using verbs (“Using the calculator”) or nouns (“Calculator options”)?

Example formatting questions

• How do we format button/field/page names? Bold? Italic? Underlined? A combination of one or more of these?
• How do we distinguish headings from text? And different heading levels from each other?
• How much whitespace will we have on the page?
• Do we have a single-sided layout (all pages the same), or a double-sided layout (left and right pages look different)?
• Will headers/footers include the document title, the chapter title, the section title, or some combination of these?
• Where will page numbers appear? Centred in the footer? Top right of the page? Always on the outside edge?

But I don’t have time to write a styleguide! I have docs to be getting on with!

Here’s a quick and easy approach to establishing an in-house style.

1. Select an existing, publicly-available style guide and start your in-house style guide with the disclaimer that “Unless our style guide says otherwise, we follow the rules from <Other Styleguide>.”
2. Have a brainstorming session to record all existing in-house style preferences that should be retained, regardless of what the 3rd party guide says. For example, “Heading 1s should use initial caps, extend into the left-hand margin space, and be presented as left-justified text in 16pt grey Garamond font and small caps.” or “Screen names should always be italicised.” or “Use the following drill-down format when telling users to select menus, sub-menus and menu items: Click A | B | C.”
3. From there on, whenever there’s a question not already answered in the inhouse style guide (“Do we use US or UK English?”, “How do we capitalize headings?”, “Do we use bold or italic for field names?”, …), check the nominated 3rd party styleguide for the answer. If inhouse stakeholders disagree with the 3rd party opinion, get internal concensus on what to do instead and put what’s agreed in the in-house styleguide.

Often once a small number of decisions have been made, there will be a logical implication for other decisions, so the value of recording the basics is greater than it might initially seem. The investment in considering the options, making a decision, and recording the outcome is always worth it. Even if you change your mind down the line, you’ll be in a stronger position knowing what consistent “wrong” thing you used to do, and how to identify that in legacy material.

ETA: Some software-related style guides available online for free that make a good starting point, since many end users will already be familiar with the conventions for the corresponding systems:

• Microsoft Manual of Style – available at: https://docs.microsoft.com/en-us/style-guide/welcome/
• The Apple Style Guide – available through iBooks: https://books.apple.com/us/book/apple-style-guide/id1161855204
• Google Developer Documentation Style Guide – available at: https://developers.google.com/style