Creating a Style Guide for Your Public Facing Documentation

Mitch Hedberg said, “When you’re in Hollywood and you’re a comedian, they want you to do everything besides comedy. They say, alright, you’re a stand-up comedian. Can you act? Can you write? Write us a script! …That’s not fair. It’s as though I was a cook, and I worked my ass off to be a good cook, and they say, alright you’re a cook… can you farm?”

If you’re a developer who’s been tasked with writing technical documentation, then you may feel a little like Mitch did when he wrote that joke.

In today’s post, we’ll discuss why having good product documentation is important and the unique challenges developers sometimes face when creating it. To help get you started, we’ll go over some of the core principles of well-written documentation, including how to create a technical style guide. It’ll be great — we’ll have you farming in no time.

The Importance of Good User Documentation

In a perfect world, you’d get to only develop apps and tools that are so incredibly easy-to-use that user documentation isn’t even necessary. Unfortunately, that’s almost never the case. Even if you think you may have released the simplest, most intuitive product in the galaxy — somebody, somewhere — will just not get it. And that somebody will inevitably be one of your users.

1. It drives awareness.

Well-formed docs, using established content-optimization techniques, can have a significant impact on your site’s organic search traffic. It’s not uncommon for searchers to become aware of a solution by finding related technical documentation in search results. Some users approach problems from the bottom up — searching for their particular use case or issue and hoping it’s already been solved for. Technical guides, blog posts, and documentation will help inspire and capture your target audience.

2. It encourages adoption.

When questions arise, feedback studies have shown that 2 out of 3 people prefer self-service help. In the era of Google, internet users expect instant access to the information they want. They expect you to have documented their question, use case or issue. If they have to spend even one minute writing an email, starting a chat, sending a tweet, or commenting in GitHub, it could literally make or break their decision to use your product. Even worse, if they deem your documentation shoddy or lacking, it’ll leave them with a negative impression of your product or brand.

3. It reduces churn.

Even advanced users who typically skip the “what is…?” and “getting started” sections often need access to reference docs. Probably most developers would agree that the fewer things they have to remember, the better. Being able to quickly call up reference documentation can be a valuable time (and sanity) saver. If they don’t like your docs, that’s one more reason for them to start looking at alternatives.

4. It collects feedback and captures data.

Feedback collected from someone while they are using your help docs can be incredibly insightful. Even if the doc they are on doesn’t answer their question, they are in a prime position and mindset to give you details about their specific problem or the information they’re after, and you can use that to help improve your next release.

If you have access to web analytics, you can use visitor data to help inform development decisions. For example, if 90% of people accessing your help docs are using a particular operating system or browser, maybe it’s time to take a look at what might be causing the discrepancy. You can use the relative page traffic and search volume by term to form testable theories around how folks are using your app, and what areas may need more focus — be it from a documentation standpoint, or the product itself.

5. It promotes your project/brand.

Like we mentioned earlier, having high-quality, indexable documentation can help get your app on the public radar. In some cases, your support docs are going to be a user’s first impression of your offering. In this way, your support docs serve double-duty as landing pages. If your documentation has a confusing structure, is hard to read, or is just plain ugly, it’s going to reflect poorly on your brand and possibly sabotage your chances at conversion/adoption.

6. It helps optimize your customer service resources.

If you’re a new or relatively unknown development agency, your support contact volume will probably be pretty low during development and at launch. If your project takes off and becomes popular (and that’s what you want, right?), you’re naturally going to starting seeing more contacts come into your support channels. You’ll realize very quickly that the personalized, one-on-one support process that you might have become accustomed to during the development phase is just not scalable (unless you’ve got tons of time and money to hire and staff a full-service support team). Having good documentation in place works as a contact deflection technique to help you make the most of your (probably limited) human support resources, and lets you get back to focusing on development.

The Challenges of Writing Documentation

To help you produce good documentation, we should look at some of the common issues that developers encounter when it comes time to put the words on the page. By identifying the potential pitfalls, you’ll be better equipped to recognize them when you see them, and (hopefully) avoid them.

1. You aren’t inspired to write.

We get it. You didn’t spend all those years at culinary school just so you could become a farmer. Unfortunately, lack of interest or years of experience leaves many developers to skimp on their documentation obligations or ignore them completely. You can tell bad, uninspired writing when you read it and so can your audience. There’s not much advice here… if providing good documentation is part of your success strategy, get inspired and put in the proper effort, or find someone who will.

2. You’re too close to your work.

If you’re documenting something that you worked on yourself, then your perspective on it is probably pretty skewed, and the longer you’ve “lived with” a project, the higher your chances of not being able to objectively describe it. Don’t feel bad — it happens naturally to anyone who becomes immersed in a particular subject. Good technical writing requires identifying who it is that will be reading your content while injecting a level of objectivity.

Later, when we talk about developing your style guide, we’ll get into identifying your audience. Knowing who your readers are — what they already know and how they think — will be an important key to figuring out how high- or low-level your particular doc needs to be.

3. You don’t have the time / the content changes too frequently.

This can be an especially challenging issue for developers with tight delivery deadlines, and technical writers who deal with frequent code or feature changes stemming from rapid, agile development.

Setting up a repeatable editorial process to outline, draft, review, update and publish content can help alleviate some of the time overhead involved, and a fleshed-out style guide can help speed things up by taking some of the guesswork out of how to format a piece of content.

What is a Style Guide?

If you’re from a web design background, then “style guide” is probably not what it sounds like. It has nothing to do with classes, background colors or type sizes.

A style guide is a collection of rules, practices and guidelines for writing for a particular publication. They are used for things like news stories, academic papers, business communications, and legal documents. You may have heard of the AP Stylebook used by the Associated Press or the MLA Handbook, which is often used for academic publishing.

While some things in a style guide are hard rules, it can’t account for every possible issue that might manifest while authoring docs. A good style guide compensates for these edge cases by providing more generic “guidelines” to follow in these cases.

As your docs continue to evolve and grow, you’ll need to address new issues as they pop up. This means your style guide is never truly “done”. Most guides operate as a “living” resource. For a team doing a sizeable amount of technical documentation over an extended period of time, maintaining and updating their style guide will be an ongoing mission.

Why Do I Need A Style Guide?

1. It provides purpose and direction.

A good style guide can help a writer get started and provides guidance when a writer has a question or is unsure how to approach a particular issue during the process. Regardless of their application, most technical documents share the same general goal: to inform the reader. Put simply, they provide knowledge.

This is decidedly different from something like landing pages, where the goal may be more action-oriented (like asking for a signup), or blog posts, whose goals are usually to generate traffic/page views.

This might seem like an obvious distinction, but when the time comes to start actually producing content, having a well-defined mission will help you in the early stages of writing a doc and can serve as a guiding light later when it comes time for updates or content quality audits.

Like we mentioned earlier, writing for technical documentation requires a certain level of objectivity. If you are the developer (or even just part of the larger team) it can be tempting to use marketing-type language to describe how “easy” or “fast” a particular feature is. While this kind of messaging has its time and place, users scanning through your technical docs will find it unhelpful at best, and downright annoying at worst.

2. It gives your docs a consistent look and feel.

In most cases, your users will be visiting multiple, different technical documents on your site. By maintaining a consistent style, you can “train” your readers how to best use your docs. By styling certain elements the same way across documents, you put less cognitive work on the reader to find what they are looking for. For example, by always putting “code examples” in a blue box after the intro, users familiar with your style will organically and naturally know how to find it.

A style guide will sometimes set formatting rules for copy. If you’ve ever read a help doc and noticed how certain action words are always bold, or how specific variables or values are always italic, those guidelines were probably established in the publisher’s style guide. Subtle context clues like these assist readers to quickly follow and understand the content.

They say you shouldn’t judge a book by its cover, but your users are going to judge your app/project by its help docs. Your technical documents’ presentation should reflect the rest of the company. In business slang, do your docs “fit the corporate image”? If they’re poorly formatted and loosely structured, they could turn off users before they’ve even given your service or app a chance.

3. It gives your docs a unified voice.

Even if your docs are authored by various contributors, they should still sound like they were all crafted by the same person. This is professional and lends authority to your content.

4. It saves you time.

When authoring technical docs, there can be a myriad of terms, acronyms, and proper names that get referenced on a regular basis. Is the second P in PayPal capitalized? Do we spell out Create, Read, Update, Delete, or can we just say CRUD? It’s too much for a human to remember it all, so having a quick, one-stop reference for things like these is going to be a time-saver. As your customer service team grows, having a style guide in place will help you train new tech writers.

5. It settles disputes.

Well… disputes between technical writers. If you have a group of people all writing the same kind of content and trying to sound like the same person, there will eventually be some disagreements over how to style a particular element or approach a particular word/name/acronym. A thorough style guide can serve as arbiter in these situations, and provide “guidance” in the absence of specifically spelled out rules. Once a resolution has been made (or dictated), the new rule or practice can be officially added to the guide.

How Do I Make A Style Guide?

1. Identify your intended audience.

This single factor will inform your technical writing probably more than anything else.

If you’re a developer, you’re probably at least somewhat familiar with the type of person who will ultimately end up using your product, and by extension, its documentation. Anecdotal and industry insight like this can go a long way into determining at what level to craft your messaging.

Web traffic analytics tools (like Google Analytics), can take this a step further by using hard data to identify technical details of your users (like their operating system, browser, where they’re from, who referred them, and what terms they searched for that landed them on your site).

If you have an existing community of users, you can poll them for valuable market research information as well.

Here are a few questions to ask yourself (and your audience) when figuring out who your reader is:

What do they already know?

Are they students just getting started, or senior software engineers with pre-existing expert level knowledge? How advanced (or remedial) your documentation needs to be will often depend on the technical expertise of your reader.

What kind of content do they want/expect/demand?

This can be closely related to the first question. Are they looking for a quick start so they can start using/building themselves without much reading investment? Do they want an in-depth explanation of all the ins-and-outs of how your solution works? Do they just want a simple table of values that they can bookmark or print into a cheat sheet?

How are they accessing your documentation?

This one might seem a little less obvious and may take a little imagination. If you’re documenting, say, how to use a new markup validation tool you’ve created, then you can probably safely assume that most of your users are accessing your documentation from a desktop or laptop from the comfort of their office desk or living room couch.

However, if you’re documenting how to troubleshoot a mobile app, that likely means most of your users will be accessing your docs from their phone.

2. Determine your goals.

Your style guide should have a stated mission or goal. It should be unique to you and your project, but in general, it’s going to be something like, “the goal of this style guide is to encourage creating technical documentation that follows established standards and is collectively consistent in style, format, voice, and vocabulary.”

Like we mentioned earlier, the simplified goal of technical documentation is to provide knowledge. To that end, when coming up with your style guide goal(s), it might help to think about what your goals shouldn’t be, as well.

Your goals should be to:

• enable the creation of consistent content
• assist technical writers
• serve as a “source of truth” for formatting and style decisions

Your goals should not be to:

• advertise/champion your app/project
• persuade users to use your app/project
• provide reasoning behind development choices/decisions
• deride the competition

3. Create a template.

Similar docs should have a uniform structure. One of the ways a style guide speeds up production and assures quality is by providing a template or example of a well-formed technical doc. To help you start brainstorming, here’s a simple example of the shape a technical doc template might take, from top to bottom.

1. Table of contents — How is this document organized?
2. Introduction — What are we covering, and why is it important to the reader?
3. Requirements — What does the reader need to get started?
4. Step-by-Step Walkthrough — What are the exact, detailed steps to accomplish the task?
5. Example — Do we provide a working example for readers who want to get “hands on”?
6. Frequently Asked Questions — Are there any common follow up or related questions that come up when using this doc or performing this task?
7. Related documents — Are there any other on-site technical docs commonly referenced in conjunction with this one?
8. Additional Resources — Where else can the reader go for more help? (community links, third-party documentation).

4. Create a word list.

Many fields and topics have a vocabulary unto themselves. Curate a list of commonly used words, phrases, acronyms, and proper names related to your project. Prescribe a preferred spelling, capitalization, and other rules around how and when to use the word. This will help promote consistency across docs and generate consensus among different writers.

As you get accustomed to your style and it becomes second nature, your word list may eventually become the most commonly referenced tool in your style guide. Once it’s in a good place, consider adding your word list to your local spell checker dictionary on a regular basis.

5. Iterate, then iterate some more.

Like we discussed earlier, a style guide is never really finished. As you start churning out docs, analyzing data, collecting feedback, and making corrections, opportunities will arise for you to add to and improve your style guide. It’s a good editorial practice to schedule regular audits of your style guide to identify gaps and make sure it is still providing up-to-date, correct style recommendations.

Conclusion

Your public-facing documentation can be your users’ first introduction to your project. It should be on-brand, helpful, intuitive, easy to read, and give clear direction to your users. Creating and maintaining a style guide will go a long way to assuring that your documentation is authored that way and stays that way. In the end, a style guide is like any other development tool — you take out of it what you put in. Now, go get cooking.