The Myth of Simplicity and Complexity in Help Authoring

After my last post in which I criticized WordPress for not hiring a technical writer to make their documentation simpler and more accessible, two things dawned on me. First, I’m an idiot for not recognizing an opportunity when it presents itself. I should write a comprehensive help file on WordPress and sell it. I’ll work on that.

Second, the interplay between simplicity and complexity is what technical writing is all about.

Although simplicity is a noble ideal, and something like “simplify complexity” could be the mission statement of any technical writer, simplicity is in fact a complex undertaking.

Let me explain with an example. If you look at any TechSmith help file, the author tries to make the content as simple and accessible as possible because TechSmith wants users to feel the inherent ease and simplicity of the application. Topics are light, short, easy to navigate. It’s quick to see what’s there.

This model works fine for the basic user just trying to get up to speed, but it fails the power user. If you look at TechSmith’s forums, users have written Support asking hundreds of questions, many of which aren’t answered in the help. For example, how do you reduce AVI file size? The treatment in the help is light, but the support forum is heavy.

TechSmith Support Forum

TechSmith Support Forum

This is the supposed tradeoff between simplicity and complexity. If you keep it simple, the documentation is accessible and easy to digest, but it may not answer many of your questions. If you try to answer all of the reader’s possible questions, the help becomes thick and heavy and the product seems complex.

WordPress is another example. If you know what you’re doing, installing WordPress really only takes 5 minutes. However, because there are a dozen different install methods (depending on your web host, the database tools, and your server access), and because various authors have added their how-to’s on the installation page, installing WordPress looks complicated.

Choosing between complexity and simplicity in documentation

Choosing between complexity and simplicity in documentation

Sure the WordPress wiki authors could strip out the installation instructions and target them for the most likely user (applying the 80/20 rule), but then the other 20% whose server setup is different from the install instructions would have trouble.

Many people will look at the tradeoff between simplicity and complexity and leave it at that. If you want it simple, you have to dumb down your documentation and leave out all of the exceptions, notes, what-if-scenarios, and other gotchas. If you want to include all of the info every possible user may ask or need, in a variety of situations, you’ll end up with a complex looking help application that intimidates users. This is the perceived tradeoff between simplicity and complexity, and it’s partly a myth.

This is where the skills of technical writing come in. A good technical writer can add in all the complexity of the system – the notes, tips, cautions, what-if’s, remember-this, watch-out-for-this-gotcha, if-you-have-this-platform, for this and that scenario – and so on, without having the help file degenerate into a hairball of complexity. This is what separates trained technical writers from basic IT people who can write coherently.

Almost every best practice of technical writing is aimed at simplifying complexity. The more techniques you employ in your help, the more powerful you become at compressing information into your help file without cluttering it into confusion.

Here are 20 techniques most experienced technical writers implement almost unconsciously.

  1. Approach the application from a task-based mindset rather than a screen-by-screen mindset.
  2. Break up the material into discrete topics that you can manipulate into different outputs.
  3. Use numbered steps in your tasks.
  4. Keep the number of steps relatively short — no more than 10 steps; otherwise, chunk the steps into subtasks.
  5. Keep sentence structures and paragraphs short and simple.
  6. To facilitate scanning, bold button names and links that you want the user to click.
  7. Include screenshots to identify where things are, especially when it’s not obvious.
  8. Use diagrams to illustrate concepts.
  9. Use examples and scenarios to strengthen understanding.
  10. Avoid unfamiliar terms and concepts (jargon, for example). Always define acronyms first.
  11. Add tables of contents with chapters or books that logically organize the content.
  12. Choose a readable font for the medium and make the size legible.
  13. Balance text with graphics to increase the layout appeal.
  14. Include video tutorials directly within help topics to demonstrate confusing processes.
  15. Write in the active tense so that it’s clear who is doing what.
  16. Ensure steps are accurate, especially after developers near the end of a release.
  17. Where applicable, use drop-down hotspots to compress multiple topics on the same page.
  18. Single source the material so you can provide both online and printed help to accommodate both learning styles.
  19. Insert cross references or hyperlinks in relevant places for more information.
  20. Be consistent in your methods so the reader can better follow you from topic to topic.

Nothing I’ve said should be revelatory to any technical writer who’s been hacking away at help for a while. But if you give the same list to developers, I bet most of these techniques never cross their minds. Adhering to these principles would be so tedious and painstaking that it maxes out their writing thresholds.

I’m not saying that if TechSmith help authors adhered to all of the above, they could fit the entire contents of their support forums into their online help file without making it look dense and complex. But to some degree, yes. To some degree, adhering to best practices does allow you to get more information to the reader in a cleaner, more organized, more consummable way, as illustrated by the following graphic.

The more best practices you use, the more info you can deliver to the user in a consummable way.

The more best practices you use, the more info you can deliver to the user in a consummable way.

Madcap Flare Adobe Robohelp

This entry was posted in general, WordPress on by .

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm primarily interested in topics related to technical writing, such as visual communication (video tutorials, illustrations), findability (organization, information architecture), API documentation (code examples, programming), and web publishing (web platforms, interactivity) -- pretty much everything related to technical writing. If you're trying to keep up to date about the field of technical communication, subscribe to my blog either by RSS, email, or another method. To learn more about me, see my About page. You can also contact me if you have questions.

12 thoughts on “The Myth of Simplicity and Complexity in Help Authoring

  1. Ryan Schmid

    Someone on this or another site said it best: “Attuning yourself to the gap between what experienced users take for granted and what novices find difficult is, of course, the secret of effective technical writing.”

  2. Craig

    when I went to WordPress to start my blog, I was overwhelmed. Having a ‘Before You Install’ to read is bad. I just wanted to get started. When I began reading it, I fogged over.

    I asked My Better Half about it. She didn’t even bother looking up. She told me to go to Blogger. I went there. They have just three steps highlighted in a big bold red typeface. Nice and simple. I followed the steps and was up and running in five minutes. My blog was started.

    I haven’t returned to WordPress since. I won’t either, unless Blogger seriously lets me down over the long haul.

  3. Pingback: » The Myth of Simplicity and Complexity in Help Authoring | I’d Rather Be Writing - Tom Johnson Writer River

  4. Pingback: Reader Question — How Do I Get Training in Technical Writing? | I'd Rather Be Writing - Tom Johnson

    1. Tom

      @Lulu, I listened to a podcast with the author. If you go to wordpresspodcast.org, and search for the book title, you’ll find the podcast. It seems pretty basic, and I don’t know who they can keep it updates with releases every quarter. Still, it may be just the thing you need to get started.

  5. Robert Nagle

    I’m a technical writer who was one of the early adopters for WordPress in 2003. I don’t disagree with your main points, but I’ve been pleasantly surprised at how manageable the wp docs have become with the codex. It looks nice and manages to answer most of my questions. I like how they’ve integrated the forums with third party products. I also like the way anchors generate a built-in TOC of hyperlinks for the same page. Also, I think the UI for wordpress is one of the easiest I’ve encountered (which reduces the need for clear documentation). The WP people have assumed (correctly I think) that a usable GUI reduces the need to document for newbies. Anyway, if people need help performing basic functions, they need a screencast, not a written document.

    I think what people need is a TOC page with a list of common tasks, from easiest to hardest. Also, it should be easy for wordpress to have hooks at various points in the interface to user-oriented documents in the codex.
    Also, they need to separate conceptual issues from practical issues. They are mixed in together, and sometimes it’s hard to find the doc you really need. Also, more than having a technical writer they need someone just to delete or prune all the pages with outdated information!

    Finally, the real pain points are not in wordpress but in theme management, change management and third party plugins. Those things are where I spend 95% of my time trying to troubleshoot.

    By the way, the drupal documentation is a lot more chaotic than wordpress.

    Robert Nagles last blog post..Back to Houston, Back to Work

  6. Jordan Frank

    Help authoring in a wiki is ideal since the page format lends itself to chunking help tips into small pages rather than chapters. Using categories can also be a big improvement as well, to add a dimension to any written TOC or index. It can also help distribute the authoring process.

    The most difficult hurdle I’ve faced is the need to focus on “how do I use a given tool?” vs. “how do I apply the tool to a given use case?”

    In the former case, you are answering “what exactly does each button do” and in the latter case you are answering “why would I use that button?” or “how would I use that configuration option to solve a particular problem?”

    The latter is difficult as the answer generally depends entirely on the organization and need for which the software is deployed. When the two types of answers start to intermingle, it adds the sort of complexity that may turn some people off.

  7. Pingback: The Naked Tech Writer « ffeathers — a technical writer’s blog

Comments are closed.