Nearly a year ago I marveled at the design of Rapidshare, which bills itself as the world's biggest 1-click file hoster or some such rubbish. The same applies to documents.
It's easy for technical writers to get caught up in the marvel of formatting. When you're writing for utter fucking morons (and the canonical presumption of end-user documentation is that they are), you want to break down the information into chunks as small as possible and feed these to your reader individually. So you avoid long sentences and long paragraphs, use plenty of screenshots, all sorts of pretty colored fonts with dropped shadows and plenty of whitespace - to differentiate conceptually separate items.
But if you're not careful, at some point you'll end up with a page that looks like the front page of Rapidshare, and that makes your document unuseable. People have a specific expectation of how information is presented. It may be difficult to find your spot again on a page of uniform text after you've looked away, but it's a skill that anybody who has ever read a book in more than one sitting possesses.
The basic dichotomy of documentation is that of a manual versus a help file. People are meant to read a manual, and look up a help file. Naturally they won't actually sit down with your manual in front of a cozy fire one winter's evening (unless it is to ceremonially convert the printout to kindling), but there's a method to the madness. Manuals are things people look up when they have no other choice, and if they're that stumped, you might as well force them to read through more than half a paragraph and learn something useful. They're sufficiently open to it at that point. Of course, it is possible to make a manual useless by neglecting effective navigation (of which markup is a part), but it's a fine line that you will simply have to find, by talent or skill.
But a page full of needless whitespace, seemingly arbitrary indentation and drop-shadow fonts is a greater crime still. Finding data on a sheet of plain text is difficult enough, but ask the human mind to parse an overly formatted page at a glance, and it will shut down due to insufficient computing resources. This is the One-Click What? Phenomenon, or, if you wish, the WTF effect.
I'm probably over-simplifying, and I know my boss (who reads this blog) will kick my ass for saying this, but if you can't make your page readable using MS Word's default headings 1 through 3 and paragraph breaks, then you're simply not trying hard enough.
The Dark is Rising
3 days ago