Photo of Ted Cox

Ted Cox is a Linux nerd, a cyclist, and LexBlog's Technical Writer. He enjoys burritos and writing bios in the third person.

OK, now that we’ve completed the Support Center redesign, it’s time for some fun. (Look, a blog named “Donuts” can’t be too serious all the time.)

I spend a lot of time thinking about how users work with our products. Sure, I know the layout and organization of our software, but some of our users don’t. When writing support articles or revising the microcopy in our user interface (UI), I put myself in the mindset of users who don’t spend as much time in the software as we LexBloggers do.

But I recently applied that thinking to another kind of user: the rogues and scoundrels who show up to my occasional game nights.

 

Different game, same rules

Every month or so I throw a game night (house favorites: Jackbox Party Pack and Cards Against Humanity) or bad movie night (past screenings: The Room and Miami Connection).

Sure, I know the layout and organization of my apartment, but some guests don’t. When people come over, I try to set things up to make the evening enjoyable and relaxing. Recently, this involves labeling the unique aspects of my home that a visitor wouldn’t understand without an explanation.

Many of the concepts that go into creating a good web UI can also apply to creating a seamless game night. Here are some of the UI rules that I’ve applied to my apartment:

 

Anticipate user needs

When showing up at the front door, some people will (politely) knock and then wait for an inebriated guest inside to yell, “It’s open!” With a note on the door (“Come In”), visitors can skip the unnecessary wait and walk right in.

 

Explain stuff new users won’t understand

Fitting with Seattle’s mandatory Socialist, Communist, Anarchist-vegan values, household waste gets sorted into recycling, compost, and landfill. My identical landfill and recycling bins sit side-by-side, so guests would often ask which is which. With a simple label placed on each bin, they know where to chuck the empty bottles of organic locally crafted gluten-free IPAs.

Confession: I stole an idea from an ex. The (L)andfill bin sits on the left. (R)ecycling is on the right.

 

Don’t make users search for stuff

“Where are the glasses?”

“Where are the plates?”

“Where are the titanium sporks?”

This grew out of a problem I faced when standing in other people’s kitchens: I don’t know where the hell anything is. And I don’t like rummaging through other people’s cabinets while they’re still in the house. So I often have to ask where every utensil or dish lives.

At my game nights, everything you need for enjoying tasty snacks sits out on the counters.

Pro tip: coffee mugs make great drink containers because they’re harder to spill than wine or pint glasses.

 

Put tools where people need them

If organic locally crafted gluten-free IPAs go in the fridge, bottle openers should be really close to that fridge.

 

Be lazy

OK, being lazy isn’t a rule for crafting user interfaces. But it gets to an idea that’s lost on many organizations: If you manually answer the same question over and over and over again, you’re doing something wrong.

Take this common game night scenario: at some point one or more guests will ask for the WiFi credentials. So I would have to walk over to the router and read off the key. Sometimes this would happen more than once a night.

The solution: notes with the WiFi information sitting on the game table.

 

Less thinking, more playing

OK, yes, some of these ideas are silly. But I’m a nerd who overthinks how people interact with stuff. And in the AirBnB age, labeling your home for guests does make some sense.

On game night, hopefully my guests spend less time figuring out how my apartment works, and more time eating tasty snacks, playing games, or sharing the best music videos.

Like web UIs, the goal here is the same. Less thinking, more playing.

As Jared wrote earlier, we employ several tools to make support documentation easily available to our users. In addition to those tools making our software easier to use, the content and structure of each article should help users quickly complete a task or understand a concept. How a piece of text contributes to a reader’s comprehension is what technical writers refer to as readability.

After joining LexBlog in 2016, I quickly focused on how we write, organize, and share customer-facing help articles. One particular task has taken me a year and counting: structuring all of our docs for readers who don’t have time to read.

 

Some points about our users

When I write or edit articles, I have to remember these points about our users:

  • On the web, people don’t read. They scan. User eyes are very good at skipping to the content they need.
  • Our users are busy. When looking at a help article, they need to find relevant content quickly. Nobody has time to read four pages about, well, anything.
  • Our users are diverse. Some of our users are seasoned web developers. Others have never logged into a blog in their life. Some may use accessibility software to help them read text on a page. Others may not speak English as their first language, so translation software helps them with the text.
  • Users get frustrated. Often a user doesn’t look at documentation until something goes wrong. The person reading a help article may already be confused, frustrated, or lost.

 

Structuring and writing support articles

It may sound like a contradiction — writing for people who don’t read everything on the page — but a few simple techniques improve an article’s readability. These are the general rules I follow when writing or editing help articles:

  • Keep it consistent. Our docs should follow the same, predictable format. New users who need more details can read more of the document. Experienced users who just need a refresher can skip straight to the parts they need.
  • Put important information up top. User eyes spend more time at the top of a webpage. So we put important messages higher in the docs. It’s a good idea to tell a baker to preheat the oven before they mix the batter.
  • Keep it short. Articles are brief and focused. Short, descriptive titles should tell you what the article is about. We limit sentences to 25 words, while paragraphs are generally limited to four sentences. If a concept requires more explanation, we may link to another source.
  • Use headers and lists. Clear, useful headers help a reader’s eyes skip to the information they need. Lists group together similar ideas or instruct users on how to perform a task. Using both of these elements can help break up a wall of text.
  • Use simple words. Technical writing is delightfully boring. We avoid jargon and pretension.

 

Learn more about readability

As I mentioned, restructuring our support articles is an ongoing task. Users like fixing their own problems, and clear, readable documentation can help them do so.

Here are some of the sources I regularly consult about writing for readers on the web: