How to Write Effective Online Help: Results from an Informal Benchmarking Exercise

My writing colleagues and I recently presented our favorite help systems. The reason: we are converting a large chunk of our documentation from PDF to HTML format, and we wanted to identify content and design patterns to consider emulating. (We’re technical writers, so this sort of thing gets us going.)

Of course, what a person likes or doesn’t like is pretty subjective, and it should go without saying that benchmarking should never replace more objective means of researching your users’ needs. Still, for us it was a fun and useful way to inform our ideas, and to find some paragons to guide our work.

Below is a list of the help systems which came up in our discussion. I’ll share a screenshot of each one and summarize some of the pros and cons we observed, and then close with some takeaways.

Arbortext Editor Help



The Arbortext Editor help is good overall, despite the fact that it still adheres to many print conventions (such as organizing topics into “books”). The topic hierarchy is organized around the main tasks that a user would want to accomplish, and is relatively easy to navigate. The procedures are clear, consistent, and free of jargon, with a good balance between too much and too little detail. Strange new terms and concepts are clearly explained when you first encounter them, and you are gradually led from basic to more advanced tasks.


Perhaps the most salient issue with the Arbortext help is that it follows the print document paradigm too closely. The content is not freely available in the cloud, which means you can’t do a Google search to turn up the topic you need. You can find some helpful videos online (example), but they’re part of a course that requires you to create an account to view all the lessons. The search tool within the help is decent, but oftentimes you get a long list of results which all look potentially relevant. Browsing gets hard because there are so many topic hubs and sub-topics within sub-topic hubs.

There are also some irritating navigation issues. The topic you’re viewing isn’t clearly highlighted in the navigation pane, and topic names often get cut off (and no, the pane is not adjustable). Some of the topics could use better inline linking.

Moreover, as is obvious from the screenshot above, the help is not terribly attractive. It has an old Windows feeling to it, with lots of small, old-fashioned icons that require a lot of squinting to read. Individual topics could use more white space so that the content doesn’t feel so crowded.

That said, what the help lacks in sub-par searchability and fancy design it makes up for in clear, functional instructions and intuitive organization. As I mention below, high-quality content goes a long way: the fanciest help systems ultimately fail if you can’t find what you need, or understand what you read once you find it.

Atlassian Help



The Atlassian online help for Confluence has a lot going for it: a slick design, an intuitive information architecture, a search engine that auto-suggests topics while you type. It does a great job of using rich, inline linking to take you to related details. (Some systems go overboard with links, but to me Atlassian strikes a good balance.) The sentence structures are simple, new concepts are clearly defined, and there is an informal tone that makes the content easy to follow. Some other good features include:

  • A breadcrumb trail to point out where you are
  • An easy way to run a search or return to the Home page
  • “Related content” sections that actually show *clearly-related* content (something I find lacking in the WordPress help)
  • Easy access to a forum where you can ask questions if necessary
  • Clean, mobile-responsive topics that are discoverable using your search engine of choice


There are occasional headings and paragraphs with excessive padding, making you wonder if something is missing. The formatting for the notes or tips feels a little too prominent to me, though I’ll admit that’s a minor quibble. The search engine could still use some improvements. (It would be great to see a “Did you mean X?” feature like Google has.)

Lego Help



Our manager really enjoyed the Lego help, and not just because of its fancy, mobile-friendly design. The main Support page contains a colorful status indicator for how well the support team is performing, and there are prominent links to topics which are aligned with common user questions. Consistent categories of information appear across the topics—categories which help you know what to expect and where to look as you interact with the system. There is an excellent search engine which auto-suggests topics for you, returns relevant results, and highlights key terms you entered. (Bonus points for highlighting search terms with elegant shadings, as opposed to a garish yellow color.) If you don’t find what you need, there’s a prominent link inviting you to contact a human.

Indeed, you really get the impression that Lego is eager to talk to you and resolve your issue promptly. That’s not a an impression one often gets from big, successful companies.


One nitpick I have is that there’s a lack of parallelism in the topic titles. Some start with gerunds (verbs ending in -ing), while others start with infinitives (verbs phrases like “How to”). I doubt this makes much of a difference to users, though.

Spotify Help



As with most of the help systems we examined, the Spotify help is freely available online and thus easy to find from a Google search. Individual topics are presented with a simple, elegant design. The ample margins and white space create plenty of room to breathe; the text is large and free from clutter like acronyms and product names; the width is manageable; the instructions are brief (very few require much scrolling, which is likely a function of the product design and the limited scope of the help). Some of the steps include an icon or screenshot of a button so that you know what to click or tap within the interface. You can easily run a search, return “Home”, or leave feedback.

One thing that struck me is that there are no toolbar buttons which other help systems commonly provide. For example, there are no buttons for “Share This Page,” “Print,” “Download,” or “Next / Previous Topic.”

I was also somewhat surprised to find that the topics have a “Last Updated” indicator. I don’t think the other systems we reviewed included this information. In general I feel that it can be good or bad information, depending on how recent the time-stamp is or the way your software is released.

For example, if your software is released in versions (as in the case of most of the Atlassian products), having a “last updated” marker is probably less important than knowing which version the instructions apply to. On the other hand, for services like Google and Spotify that do not have specific versions (at least not that the end user cares about), the time-stamp may be a more useful way to reassure readers of the currency of the information—so long as the last update was relatively recent. (In the case of Spotify, all the time-stamps I saw were within the last few months.)


I have two criticisms of the Spotify help. First, the “Listen Everywhere” list of links in the left-hand navigation is rather ambiguous. If you were to click on one of those links, what would you find?

Second, although the step-by-step instructions sometimes include a picture of the button or menu that you need to select, they do not always include the names such elements. That may be okay if you don’t need to worry about localization or accessibility, but it would be a big problem for our team since we need to ensure our content is accessible and as conducive to translation as possible. That usually means you have to include the name of a button in addition to its icon, since sentences often get re-arranged during localization, and you can’t always predict where the icon will end up.

WebWorks ePublisher Help



There is not much to like about the WebWorks help. The search engine is pretty useful in that it shifts dynamically and highlights key words as you type. The pages are mobile-responsive, and the content is not always bad once you find it and follow the instructions. But even the best features are seriously outweighed by a host of other issues.


To begin with, there is way too much marketese sprinkled in with the help. (See this page, for example.) The result is a lot of muddied, distracting information. To make matters worse, much of the marketing material appears in prominent areas (such as the Welcome page), while the more practical help content is buried in lower pages.

The page layout and design needs a major overhaul. The text is too small, the pages are too wide, and there is a giant Disqus commenting section that spins and loads with each page you open, drawing a disproportionate amount of attention to itself. A lot would be improved by simply removing this area. (None of the topics we read had any comments on them.)

Lastly there are some noticeable content problems. We found several topics with screenshots that were too small and blurry to be of any use. Some of the procedures are overly long. The “Home” icon in the top-right corner of the system leads to a useless splash page with no links or text. The social icons and “Print this page” icon add unnecessary clutter. (Does anyone really need those features?)

In short, the ePublisher system is a fine example of what not to do.

WordPress Help



The WordPress help has a lot of the same admirable design qualities which we saw in the Atlassian, Lego, and Spotify help. There is ample white space, a readable page width, a mobile-responsive layout, and an easy way to return to home if you need to. The content follows certain principles of effective web writing.

For example, in the Stats page (which the above screenshot is from), the documentation is organized so that the order of information matches the order of the user interface elements. The feature descriptions provide additional context that you don’t get in the UI itself (i.e., it doesn’t just state the obvious, which a lot of help content ends up doing).

The WordPress help also presents an interesting contrast with the Spotify help. In WordPress, a single page is used to contain a rather large amount of information, whereas in Spotify the topics are much shorter. Thus an “On this page” menu and “Back to Top” links are useful in the WordPress page, but such elements would probably be unnecessary in the Spotify topics.


My biggest gripe with the WordPress help is that the list of links on the right seems overly long to me, and I am not convinced of the value of the “Topics” link category. Also, the “Related” links section is kind of buried—and it isn’t clear to me how some of the links there are actually related.

Key Takeaways

Several strategic themes emerged from our analysis, and I’ve listed them below in loose order of importance. Note: These are pretty general and observational in nature; they do not include links to books or more empirical research. I may later update this page with a few references, or write a follow-up post to connect these takeaways with respected sources.

1. Define what well-written content is, and focus on delivering it (even if you can’t use an advanced search tool or a spiffy design).

Let’s state the painfully obvious: a poorly-designed help system can still have well-written content and therefore be more useful than a slick-looking help system whose content is mediocre or just plain bad.

For example, while the Arbortext help falls far short of modern web design standards, its content is well-organized, easy to read, and relevant to what the user needs to know and do. By contrast, the WebWorks ePublisher help is sloppy, unclear, and difficult to navigate despite having a mobile-responsive web theme and a handy search engine.

Of course, you have to ask what qualifies as “well-written.” Here are just a few characteristics of effective web writing we noticed (characteristics which are all highlighted in the Microsoft Manual of Style, 4th Edition):

Freestanding, richly-linked text

  • Contextual cues and introductory information that allows each page to stand on its own (i.e., content that accounts for the fact that “every page is page one“)
  • Relevant links with descriptive titles
  • User-friendly keywords embedded in topic titles, paragraphs, and cross-references

Readable text

  • Plain language focused on simple sentence structures and short words
  • Consistent presentation for concepts, procedures, and other content types
  • Few if any acronyms or elaborate terms and product names

Scannable text

  • Short, parallel headings
  • Digestible paragraph chunks
  • Plenty of white space between paragraphs

Organized text

  • Important information and conclusions first (i.e., text that applies the “inverted pyramid” writing principle)
  • A consistent structure and parallel categories where applicable
  • Intra-page navigation (such as anchor links) for long pages

(Side note: I published an in-depth article about structure and organization patterns if you’re looking for some ideas on that front.)

2. Let your users get to the help from a Google search, if possible (or at least from some kind of hypertext search).

Almost all of the help systems we examined could be found by running a keyword search from a major internet browser. In fact, most of the help topics we read were found not by searching the help system itself, but by starting with a Google search. This often meant we ended up within a help system’s inner sections rather than starting from the “Home” page.

Now, I fully recognize that not every technical writer will have much control over whether their help is fully accessible online. A lot of companies have no choice but to keep their product features behind a secure login. But even those companies are still moving many of their applications to the cloud, which means using a web-based search strategy is paramount. So if and when you ever get a chance to advocate for more discoverable web help (as opposed to only keeping all of your help within PDFs), jump all in and make the best case for it that you can.

3. Create killer landing pages—and make it easy to get back to them.

Instead of opening your help with an “Introduction” page that has a self-explanatory paragraph and no links (which is pretty much the default starting point for so much PDF documentation), create a “Home” page that functions more like a dashboard of links. Consider these Google Docs help topics, for example.

Also: always make it easy to return home. In all likelihood your readers will search and browse their way through your help in a sort of berry-picking fashion. The home page is their anchor for starting over if they need to.

4. Re-assess the need for each and every toolbar button (and remove them if possible).

A lot of authoring tools generate help systems that display certain toolbar buttons by default, such as “Share This Page,” “Print This Page,” “Download as PDF,” or “Next Topic / Previous Topic.” It is telling that most of the help systems we reviewed have none of these buttons. Yes, there are some users who like to print things, and maybe in a moment of sheer excitement you’ve shared a help topic before on Twitter. (Please send me a link or a screenshot if you have, because I would love to see it.) But do your users perform these tasks often enough to warrant the risk of cluttering the interface? My guess would be no.

5. Re-assess the need for front and back matter topics (and remove them if possible).

By “front and back” matter topics I mean things like “Intended Audience,” “Document Purpose,” “Document Conventions,” and “How to Use This Document”—sections which print documents are known to have. None of the help systems we reviewed had these topics, probably because the authors believed that their readers already assume much of this information already, or could pick it up quickly from the context. Barring some kind of legal requirement, these are probably good candidates for omission.

There are exceptions (as with the rest of these principles). Sometimes you really do need to know whether a document or training module is designed for your particular level of expertise. But we didn’t see this much in our evaluation.

6. Take advantage of the robust linking capabilities of the web (but don’t overdo it).

The best help systems in our analysis provided richly-linked networks of topics, demonstrating time and again that links are a powerful way to help users get the information they need to solve their problems. But as some of my comments above suggest, links can also be distracting, confusing, and visually overwhelming. How do you strike the right balance?

That’s pretty situational, so having a good linking policy is important. What sorts of things should you link inline, and what should you leave to something like a “Related” section? Is there a common linking format and style that each writer should use? (For instance, you should definitely use a good title or description of the destination page rather than inserting the phrase “click here.” But most web writers already know this. The more difficult question is will always be: what is the most descriptive link title to use in each situation?)

7. Make it easy to rate content, give feedback, and contact support.

Every help system we reviewed offered these capabilities, and the best ones made it extremely easy to take advantage of them (as opposed to burying the functionality in a low-profile location). That said, these features generally require technical infrastructure that a writer may have little or no control over. In such cases your best strategy is probably to facilitate access to your organization’s support site.

8. Consider how to incrementally move toward a mobile-friendly format for your content.

Making your content “mobile-friendly” may not be your top priority, which I totally understand. For one thing, it may not be technically feasible. Even if it was, it may not be necessary: a lot depends on the primary ways that your target audience will interact with your information.

For example, one of our documents has a lot of multi-column tables that don’t display well on smartphones or tablets. Should we invest in converting the tables to a more mobile-friendly format? Right now the answer is no, since the target readers are very unlikely to read this particular content on a smartphone.

Still, there are small steps any writer can take to prepare new documentation for a mobile-friendly display. For example:

  • Flatten your topic hierarchy. Or maybe display no hierarchy at all (in which case depend heavily on search, which is essentially the Wikipedia approach). Or maybe display a contextual hierarchy that only shows items that are closely associated with the topic currently being viewed. (These latter two strategies were common among the help systems we examined.)
  • Avoid tables with more than two columns. Once you hit three or more columns, you risk serious mobile display issues.
  • Avoid ordered and unordered lists with more than one or two levels. As a rule of thumb, if you have to go deeper than than two levels, you can probably break up your list or procedure into smaller chunks.
  • Watch out for overly long titles and headings. You can usually spot these by testing how a heading looks when scrunched up on a mobile-size screen.

In case you’re interested, I’ve written about these strategies before in an article on designing wiki templates for the web.


Our takeaways were not comprehensive or particularly new; most if not all them can be found in reputable textbooks and articles. The important thing for us was to see live examples of help content done well, and to get an internal dialog going about what strategies to pursue and how to implement them in specific ways for our situation.

If you’ve got insights from your own work, or have an idea or resource to share on this subject, leave me know in the comments!