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.
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.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.