Style Matters

Something I learned after a few years of writing books, was how much style mattered in comprehension of technical material. It became the first thing my graphic designer and I worked on when starting a new project.

We would do mock-ups, fit the material into the proposed format, and try to think of exceptions that needed to fit well into the same template. “Yes, that table of contents looks great, but what about this chapter that has 25 topics?” “Let’s verify the way we want to format a menu item in the text. What if when we’re describing this process, it looks like a big wall of black text smeared together?”

When deciding where to begin, we first scoured books and websites to see who was doing it right and who was, umm…. needing to improve their presentation of information. :)

  • Look for concise explanations of why the page is relevant, so people can quickly determine whether or not that page will help them.
  • Break large sections up with subheadings, so it’s easy to jump ahead or remember where to resume.
  • Use changes in color, font-family, font-weight, font-style, all caps, and/or font-size to delineate sub-sections to view from action items and plain text.
  • Be sure the entire process is laid out on one page whenever possible. Links or page references are ok at the very beginning and end (like pre-requisites and supplemental information), but do not make them leave the page midway through your steps to do other steps before they can continue.
  • Use unordered lists to highlight important information. Use numbered lists for steps that cannot be done in a different order. Having content separated into lists allows customers to relay to technical support where exactly they are stuck, “I am on step 3 on page 195 of this book.”
  • Images aid in comprehension, but too many can interrupt the learning process. Skip images for simple steps like “Click File > New,” but do include images for complex interfaces that have text inputs, radio buttons, dropdown menus, and other form fields. If there are a lot of steps, consider an “After” image so students can compare settings before they jump to the next section.
  • Once you think you have your template finalized, see if it passes the “Squint Test.” If you stare at it and blur your eyes, is there enough whitespace? Do the headings and sections stand out enough? Are you able to see the sub-sections to view and action items jump out from the text behind? Could you follow them without the rest of the text on the page? Do you have enough images or too many? Are there any formatting or flow issues?


What does this all mean? Let me show you with some examples.

Here’s a random page from Apple’s support site:

I like the following:

  • Device mentioned in the page title
  • Where the error message might appear
  • What the error message is
  • Picture of the error message, so people skimming the page can see it and immediately know it matches what they see
  • Clear headings for symptoms, resolution, and additional information
  • Link color very different from the text color

If I could change the page, I would:

  • Change each of the unordered bullet points to be a separate resolution in themselves with directions on how to do each
  • Add options to contact support or give feedback on the page



Here’s a page from Adobe’s support site.

What I like:

  • Clear headings
  • Decent intro so visitors can decide if the page is for them
  • Products Affected section on the left
  • To the top links for a very long page

If I could change the page, I would:

  • Are there different error messages you receive when you cannot open a PDF? Should they be listed here with links to their own resolutions?
  • Remove filler sentences like “Try the suggestions below as your first troubleshooting steps.”
  • Highlight the correlation between the first three bullet points and the headings below Problems with PDF file (should that be an A.B.C. section? should it be links?)
  • Make the difference between headings more distinct “Problems with PDF file” and “Password-protected PDFs” don’t pass the squint test.
  • Italicize action items like “To open this type of document, enter the password when prompted.” to separate it from the rest of the paragraph.
  • Shorten the text-smear for Non-compliant PDFs (switch to a bulleted list of what makes something non-compliant, and add links or action items if possible).
  • Don’t strand the customers with suggestion to “repair the installation” in a bullet point that isn’t linked or suggested that it’s related to the content that follows. Would accordion menus help or just be an annoyance?




Here is a page from Microsoft’s support.

What I like:

  • They are experimenting with headings as accordion menus
  • Print, email, and translations links all at the top
  • Articles have ID numbers for easy reference (Think about a customer calling you and saying “I’m looking at article ID 888019″ versus “I’m on http://www. yourwebsite dot com slash this folder, next folder, next folder, this page name, dot file extension.”)
  • Link to support in the sidebar

What I would change if I could:

  • This page is very busy. The squint test reveals the Customer Support agent’s photo and anything in blue is most important on the page. Perhaps pictures in the article (instead of in the sidebar) and less blue would help reduce customer support inquiries and increase comprehension and retention of information.
  • Color makes things stand out. Lessen the importance of links like “Back to the top | Give Feedback” and Related articles and From the Community, so the Symptoms, Cause, and Resolution have a chance to be seen.
  • The headings under Resolution don’t work. They smear into the body of the next steps. Combined with the bolded items in the steps, it makes it look more difficult to follow. Don’t scare them off with the way you present the information. I would experiment with the font-weight, font-family, and color to make the separation more clear.
  • Blockquote, in a blockquote, in a blockquote, in a blockquote. If you look under Resolution, each section is indented from the next thus reducing the amount of room to write in.
  • Needs more pepper italics. Not everything can be bold.
  • When a visitor needs to type in something, put that information on a new line by itself so it can be easily copied and pasted.
  • It’s important to tell people where to click, but step 1 under Change Permissions is getting in its own way. Would you rather see and follow:
    “Click Start, click All Programs, point to Accessories, and then click Windows Explorer.”
    “Go to Start > All Programs > Accessories > Windows Explorer.”


Here is a page from T-Mobile’s site:

What I like:

  • Article revision dates
  • Distinct headings
  • Links to other articles on important words. It’s good to see “How to enable POP3 access…” as blue and not the word “See” linked as blue.
  • Resolution steps are numbered

What I would change if I could:

  • Reduce the number of bullet points. There’s a balance and this page is going too far in the organized-page direction. Change “what happens and why” and “probing questions” to paragraphs to see if the page can be read more easily.
  • Remove redundancy (heading “What happens and why” followed by “Possible causes include the following:”)
  • Remove the author names from the client-facing side. It’s ok for technical support to see this while editing, but the customers don’t need to know tmo_brian created it or tmo_josh edited it.
  • Pictures?
  • Step 2 at the bottom says “in the email account settings” but does not state how to get there. If this is a page that is supposed to encompass many different devices at the same time, a caveat at the beginning should be included saying so. Whenever “see the user manual” is referenced, that would be a great time to link to a table of contents of all the user manuals uploaded to the support server. Relying on the customer to have a piece of paper they probably stored or threw away, then not linking to where they can find the information online will cause customer frustration.


I hope these tips and style breakdowns help you appreciate good technical support design when you see it. As you can see, not enough hurts comprehension and too much makes directions difficult to follow or appear intimidating.

Find your own balance. Use support staff, customer feedback, and beta tester groups to help you find that balance.

Incorporate feedback

Technical writing can be improved so much by interacting with those who are actually using your instructions.

  • Do your customers understand the directions?
  • Do they still have questions?
  • Are you approaching their question the way they would be looking for an answer?
  • Can you explain better?
  • Where do they get stuck?
  • What are the most common questions despite the support page that exists?
  • Will improving the support page fix the issue or is it indicative of a deeper problem?

Writing support articles and tutorials is incredibly rewarding,… when you get feedback. Here are some ideas for incorporating feedback into your workflow:

  • For online documents, add a yes/no survey at the bottom of your page asking if this helped answer their question. When they click No, prompt them to write what other information might have helped. You’ll gain insight into documents that don’t exist but should, search patterns, and customer confusion.
  • Get out and teach. If you write beginner articles, go teach some beginning courses. If you write about advanced techniques, do a Google hangout with advanced customers and see what’s still unclear. It doesn’t need to be in a classroom, be creative.
  • Try doing some technical support for others. Whenever you encounter a question, keep track of it. If you notice at the end of a day/week that you’re answering the same question over and over, chances are the process needs improved and the documentation is inadequate. Go fix what you can. Even the smallest improvements will help with the number of questions. Check out the incoming email and forum questions to see if you can build a top 10 list of things you need to fix first.
  • Build a testing group. Get some friends who have never used your product to try it out while you’re nearby. See where they get stuck. Get a group of active users to be your beta testers. Reward their activity with early feature accessibility and presents. Or, you could even hire a group of testers from Craig’s List. There are a lot of options for making it easier for new customers and keeping power-users happy when you include this kind of testing.

Once you know what needs explained more thoroughly, you can use customer feedback during your writing and editing process.

Be Consistent

Another important part to technical writing is being consistent in the way you word and style directions. Having a style guide that you follow will help you immensely.

Here is a generic group of steps:

  1. In the top menu bar, click FILE > New.
  2. Add and edit your content.
  3. Click on File -> Save As in the navigation.
  4. Name your file and choose the location where it should be saved.
  5. Start another file by clicking New in the File menu.
  6. Type something and write some content.
  7. Up at the top click on File → Save As.
  8. In the typing box where it says “File Name” give it a title, then click the Save button.
  9. Quit the application.

Those instructions above make my want to cry.

Do you see the ways that the directions to navigate are all different? (1, 3, 5, 7)

FILE > New
File -> Save As
New in the File menu
File → Save As

Not only are the styles different, but so are the words indicating the method.

In the top menu bar, click…
Click on… in the navigation
by clicking … in the … menu
Up at the top click on …

You can find your own style through:

  1. Practice – write more!
  2. Reading – read more! Pick up some instruction books at the book store. Browse through some online product guides. Good documentation is not just about the words, it is everything from the colors, images, instruction style, and thoroughness involved.
  3. Teaching – see what instruction styles work better than others. Use your teaching opportunities to say your instructions aloud and see if they stick to your audience. If you see blank faces and no comprehension, try wording it a different way and watch for the “aha!” moment when they get it.
  4. Communicating – talk with coworkers to build your style guide. If you get your coworkers to care about style guides, chances are they may use them as well.
  5. Iterating – nothing is perfect the first time, but you have to start somewhere. Write it. Improve upon it.

Be Concise

There are lots of times when I want to start writing something and then I feel like I’m getting too wordy. You want your writing to have personality and humor, but does it belong in technical documentation?

I love it when people get to the point. They write as little as possible to convey the directions. 

Be clear. Be accurate.

The Missing Prompt

After a very pleasant conversation with a friend and colleague, Michelle, I’ve come to realize the source of my blogging inconsistency may have less to do with the busy schedule as the mom of two toddlers who works full time, but more to do with a missing prompt.

I encourage you all to think about one thing you care passionately about and write about it.

I’ve chosen my prompt and will dedicate future posts to improving technical writing. I won’t be deleting my old posts (even the ones of my fuzzy bunny Monty Python slippers), because the journey to this realization is important to me.

EDIT: Ok, so the mom of two toddlers part is definitely a part of it. 08-25-14