The Myth of Simplicity and Complexity in Help Authoring

by Tom Johnson on Aug 1, 2008
categories: technical-writing • wordpress

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.

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.

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.