What a good help section looks like

For reasons that aren't worth going in to, Tyler and I have recently begun the process of setting up a server through Rackspace's cloud services. I've never used Rackspace before, and all I really knew was that (1) they're expensive (though this doesn't actually seem to be true, at least for their cloud options) and (2) they have great customer support. From our limited experience, this latter point seems spot on, even though we have yet to communicate directly with anyone at Rackspace.

Now you might argue (understandably) that this is a silly statement to make given our lack of actual experience with anyone at Rackspace, but if you've ever set up a web server, take a look through this getting started guide, and you'll see what I mean. If you haven't ever set up a web server, I'll just say (1) count yourself as lucky, and (2) it's generally much more difficult than it should be for a number of reasons, not the least of which is the generally awful documentation available at various web hosts.

It took me a while to figure out what exactly about the help section made it so usable, but Tyler recognized it pretty quickly (from our chat transcripts):

I really like how it doesn't bother with options. It's like "here's what you want to do. Don't do it any other way." That's how advice should be. If I know enough to decide for myself, I wouldn't be reading the tutorial in the first place.

While I agree that this is part of the success, there's a second aspect that is similarly important. Even though they only tell you one way to do things (basically), they fully explain the reasons for doing it that way. That combination is a surprisingly rare one, and I think the principle is worth keeping in mind if you're ever in a position to put together materials for training, be it online or in person.

Most help/advice falls to one extreme or the other: you either get an exact prescription of what to do without any rationale, or you get a full description of many different options without any real structure. With the former, you can very quickly run in to problems if anything at all unexpected happens (like if some options change after a couple years); the "help" may be rendered completely useless. With the latter, you need to be an expert to derive much utility from the many options, leaving even a moderately-advance user without much help.

Even giving a clear path while also explaining all the options can be a tough route to follow, as the "clear path" can be easily obfuscated by all of the options, particularly if decisions aren't independent of each other (e.g., the options in step 2 impact the options in step 5). The beauty of the single, well-reasoned path is that it provides help to both beginner and advanced users. The simple narrative is easier to follow for those who are still learning, but the added depth in each part can help give more advanced users a foothold on how to approach more detailed configuration.

Even if you're not writing documentation for software or a website, the chances are pretty good that at some point you'll be trying to explain something that you understand well to a customer who doesn't. Sometimes one of the extremes (directives without explanation, or exhaustive list of options) is appropriate, but a well annotated narrative is likely to be a great option in many cases.