Special

Introducing the “Welcome to Xojo” Bundle!

New to Xojo and looking for guidance? We've put together a terrific bundle to welcome you! Xojo Bundle

This bundle includes six back issues of the magazine -- all of year 21 in printed book and digital formats -- plus a one-year subscription (beginning with 22.1) so you'll be learning all about Xojo for the next year. It's the perfect way to get started programming with Xojo. And you save as much as $35 over the non-bundle price!

This offer is only available for a limited time as supplies are limited, so hurry today and order this special bundle before the offer goes away!

Article Preview


Buy Now

Issue 2.6

COLUMN

Help!, Part III

The fine art of documentation

Issue: 2.6 (July/August 2004)
Author: Toby Rush
Author Bio: Toby Rush is a music instructor, consultant, freelance programmer, web designer, husband, and Dad in Greeley, Colorado.
Article Description: No description available.
Article Length (in bytes): 10,213
Starting Page Number: 44
Article Number: 2622
Related Link(s): None

Excerpt of article text...

Over the last few columns, we have talked about how to write a program that doesn't need a user's manual. Once you've gone over your program so that every window and dialog box is so user-friendly that no one could ever possibly need to even consider reading a user's manual, the next step is to write a user's manual.

Writing for Dummies

We'll forego diplomacy and tact for a moment to emphasize the most important aspect of writing a user manual: You need to assume that your user is a complete and utter moron when it comes to computers. Hopefully, of course, all your users will find your program easy to use and not even need the user's manual. But those users who, for whatever reason, don't "get it" -- they're the ones who will become frustrated and angry if you don't provide them with some comprehensive and well-written documentation (and, as luck would have it, tell legions of other potential customers about their experience).

In keeping with the concept of writing for the computer-challenged, here are some things to consider while writing your user manual:

Be consistent. Adopt some standards and stick to them. For example, if you are referring to "the mouse pointer" in one section, don't switch to calling it "the cursor" in another section. This goes for the fine details, as well: don't put menu item names in quotes in one chapter and leave the quotes off in the next chapter. It doesn't matter too much what format you use, so long as you're consistent with it. If you need a model, however, the vast amount of documentation available at Apple's Developer web site can provide you with plenty to go on.

...End of Excerpt. Please purchase the magazine to read the full article.