Help Docs: an occasional series on creating better technical documentation

image courtesy of wikimedia commons

Let me tell you about a bad customer/user experience I had about 15 years ago that still has me a little jaded.

One summer, back in high school, I saved every dime I made and bought one of those monstrous, all-in-one weightlifting machines.

The machine, to say the least, was overly complicated to put together, as if it had been designed in Tim Burton’s imagination—elaborate pulleys, odd parts, sharp cable wires, and bags and bags of screws and mis-matching washers (all of which I was to build with a single, impossibly small Allen wrench).

But the worst part: the instruction manual didn’t make any sense. It was incomplete, the visuals didn’t match the copy, and some of the instructions were just plain wrong. So there the machine sat, for weeks, until I was able to figure it out, free style.

Naturally, you can understand my concern now anytime I’m about to spend my hard earned money on something that requires an instruction manual.

This, of course, includes software.

The importance of quality documentation

It should probably go without saying that software, including web apps, should also come with good technical documentation.  This includes, for example, installation, configurations, and end user guidance.  One common belief, however, is that if the software is designed well enough, and intuitive enough, it probably doesn’t require any documentation. Some would call that belief laughable, but I’ll be a little more lenient and say that while some software might not, most do.

If you’re lucky, and your product is used by millions, you could probably get away with including only skimpy, lazy documentation, and let third party publishers, like O’Reilly, do it for you. There’s a reason The Missing Manual: Mac OSX was a huge seller for the publisher—when I bought my last Mac, the included manual for Leopard looked like a CD insert.

If you’re not Apple, Microsoft, or Adobe, you’ll probably need to be a little more comprehensive.

Here at Newtek, we definitely understand the importance of good documentation, and we continually work to improve, expand, and enhance the documentation we provide. Last year, for instance, we upgraded our KB system to a new platform, and have since incorporated more visual and video based articles. More recently, we began including a cookbook for dedicated servers to make initial setup easier.

In this occasional series, we’ll discuss best practices, provide tips, and review tools that can help your development shop create better, user-friendly documentation—whether that documentation is for end users, IT professionals, or the technically challenged.  Stay tuned for the first post in the series, where we’ll discuss an easy and free tool to mark up screen shots.

VN:F [1.9.1_1087]
Rating: 0 (from 0 votes)
Share So Others Can Enjoy:
  • Print
  • Digg
  • del.icio.us
  • Facebook
  • FriendFeed
  • LinkedIn
  • MySpace
  • StumbleUpon
  • Technorati
  • Twitter
  • Tumblr

Leave a Reply