Write quality help center content

Getting started guide

I wrote my first Help Center (or “Knowledge Base,” depending who you ask) without any on-the-ground experience working in Support. It probably showed.

It was written through the lens of a power user wanting to document every aspect of the product thoroughly. A noble intent, to be sure. This meant not only tons of screenshots and walk-throughs of all states of UI flow, but also big walls of text with elaborate explanations, and an enormously high number of pages (well over 400).

It made sense at the time to pick apart the product this way, but over the following year and a half interacting with both users and the product team, I came to gradually realize how backwards I was approaching it originally.


Less is more.

People don’t go searching for help articles because they have an hour they want to pleasurably spend parsing through a technical treatise to solve a fiddly problem they should not have in the first place.

Users are simply looking for the shortest path to satisfy an intent.

  • Give it to them ASAP, and get the hell out of the way.

Satisfy user intents.

At its best, software enables you to do things. To achieve some over-arching objective, by actualizing smaller intents along the way into achievable steps with the tools at hand. The user might stumble in that process for a variety of reasons:

  1. Users don’t understand how the product works.
  2. Required steps to satisfy a given intent are non-obvious (e.g., hidden or poorly-designed).
  3. The intent is outside the scope of the product. (e.g., you_can’t_do_that).

→ This is where Support lives: in that grey-world of either misunderstanding leading to frustration and insanity — or the smooth routing of questions to answers (like in an old-timey switchboard) invisibly serving the actualization of human intents via a product in harmony with its user community.

What can I say, I’m still a Support Utopian at heart!

With that vision in mind, here are a few other guidelines I’ve been operating under in my second go-round at writing a help center.


Title using active verbs and fewest words possible.

Every microsecond someone has to take parsing your help content is multiplied against the sum of their existing frustrations. Use fewer words to reduce their Time To Solution to almost zero so they can get on with their life…

As someone on the computer all day, text also can become very fatiguing. Reducing word counts and even character counts wherever possible can make a help center a place of visual as well as psychological relief.


How-to articles begin with ‘To…’

Call me old-fashioned, but I think a good rule of thumb is: how-to articles begin with ‘To…’

So, let’s say your short page title is “This thing.” Not Shakespeare, but it will do. With rare exception, then, the first words on the page should be:

To do this thing…
  • It’s basic.
  • It gets to the point.
  • Immediately useful.
  • You know why you’re there.
  • It can be linked out to from product for really specific usages.

More broadly: the article acts a link in a tool chain to achieve an intent for the user in your product. Not as a further blocker or source of confusion for users who never wanted to go sifting through your help center for a solution in the first place. Help them get done, and leave.


Minimize surface area to reduce maintenance.

The first time I wrote a help center, I thought documenting every little thing visually would be a great aid to customers. Maybe for some it was, but then I learned what “continuous innovation” means in the SaaS industry. It means your product is literally always changing. From week to week, or even day to day.

In a practical sense, then, the more material you include in your help center content, the more you will have to constantly monitor and update as the moving target of your product changes.

Not just that, but the more images you have, the more images you potentially have broken. The more links, the more dead links. And so on.

It sounds counter-intuitive to the old me, but now seems better to:

  1. Minimize images.
  2. Minimize cross-linking to other pages.
  3. Minimize repeatetion content on multiple pages or sections.

And anyway, if your product is good, nearly every operation performed in it should be easily describable in words. You shouldn’t need umpteen-million screenshots.

So, only include a screenshot with arrows in an article if it’s a complex operation and words alone aren’t sufficient to convey the user action required.


Write for Google Rich Snippets.

When people search “how to” information on Google, Google tries to automatically excerpt relevant information from websites. I made a big collection of these as reference here:

Google refers to them as “Rich Snippets.” They look like this:

Google finds a well-ranked page in its index whose title matches the user intent, and tries to yank out relevant step-by-step information, with a single small picture if available.

I did some tests with character count on these snippets from a variety of how-to searches on Google and came up with an approximate count of ~360 characters.

Given the direction automated information extraction is going, write expressly with the goal of having your how-to information accurately picked up and re-transmitted by Google to the user.

It used to be that you wanted people to visit your help center. And that may still be all well and good for certain things... But if a user can now get the answer to satisfy their intent right in the search results page, there’s literally no reason for them to ever go to your help center.

And in fact, that’s better for everyone. Their frustration and TTS (Time to Solution) drops to almost nothing. They can close the tab and bounce back to the task at hand. They don’t even have to *think* about navigating around looking for answers, getting more frustrated, and finally opening a help request.

So how do you write for Google Rich Snippets? Allow me to demonstrate:

To write help center articles for Google rich snippets:

  1. Choose a short relevant title for your page, focusing on the user intent served.
  2. Begin how-to articles with “To do ____” and answer that question as concisely as possible.
  3. Use numbered lists.
  4. Break everything into short singular, but substantial steps.
  5. Aim to deliver your information payload in under 400 characters.

If your information can be conveyed in one or two sentences, answer it immediately first and explain it or support it with details after.

An alternative or supplement to numbered lists, especially for very short answers with few steps is to use a right-bracket ( > ) between linked steps. Like:

Click on the bubble > click the field > start typing

It’s clear. The clauses are short. It’s easy to parse that they are sequential steps. I personally find it preferable to a more “correct” English sentence which might read like:

First click the bubble, then click the field, and then start typing. 

Both have their advantages, appropriate audiences and contexts, but I’m a big > guy. Seems more “Support-y” to me. Makes me feel like I’m a robot.

Speaking of robots… 🤖


Automation is radically changing Support.

Google Rich Snippets is the tip of the iceberg of the tidal changes that are underway beneath the surface of Support.

If we think of Support as routing questions to answers with the aim of satisfying user intents, human agents may soon be both augmented and eclipsed by bots, natural language processing and integrated automations.

Yes, Support should be about empathy, and your agents shouldn’t rely solely on macros and shortcuts. But if they don’t use automation tools at all, they’ll be reproducing work for no reason — work that can be easily handled by bots as they improve.

Basically, I’m thinking of Support nowadays as a process and mechanism of wiring together some combination of the following:

  • A source of questions
  • A bank of answers
  • Identifying user intents
  • Product feature map
  • What capacities Support agents have

Most problems users face aren’t unique. Most problems express themselves as repeating patterns with one or two preferred solutions.

I look at it almost like the I Ching: there are (figuratively speaking) approximately 64 possible outcomes, configurations, or arrangements users can get into relative to your product which cause problems. And for each there is a fix, a workaround, a linked work-flow or a big fat “No,” which is required as a response.

Some are big and common issues. Some are bugs that get solved rapidly. Some are #knownissuenotfixed. Some are things that come up only rarely for a few users in special circumstances. Whatever they are, they form patterns.

And where there are patterns, there is the possibility of detection and of automation of subsequent workflows.

While chat-bots running natural language processing aren’t yet fully-featured enough to be able to independently run a help desk ticketing solution without human intervention, that day is definitely coming. The race is on.

What will remain in demand as that Support Singularity approaches will, of course, always be clear, concise, brief, consistently micro-formatted documentation which can be cut up and manually or automatically reassembled based on circumstance, product state, and user need. So in effect, the game will change, but the rules will stay the same.


Other miscellaneous rules, because I’m running out of time.

  1. Write in an active voice. Be direct and declarative. Don’t mince words, muddle around, or waste people’s time.
  2. Help centers are for factual statements about how things work now. Marketing and future product promises should go somewhere else.
  3. When ordering lists of pages, start with the positive actions users can take at the top (e.g. “Make something”), followed with the negative stuff they can do (e.g., “Delete your account”) and ending with the things they just can’t do with your product (e.g., basically any FAQ which starts with “How can I ___?” and whose answer is “You can’t.”)
  4. Don’t lock things up into long paragraphs. Break to a new line as soon as a new idea arrives, or throw in a bullet point to split things up for scan-ability, and eventual automation.

Okay, that will have to do for now. Good luck!