OT: Doc Bugs (mine!) - A Lesson To Be Learned

[Paul Looney]

Ken,
Thanks for the ever-timely reminder.
I'd add one rule I consider critical:
Get a "typical" user to read the docs and run the software while you  
watch and take notes.
Paul Looney


On May 31, 2008, at 3:18 PM, Ken Ray wrote:

> As you may have already seen, I released a new version of the STS XML
> Library today. One of the main reasons for doing this is that the  
> previous
> documentation, which I had prized quite highly as being clear,  
> thoughtful,
> and informatory.
>
> Someone who recently purchased the Library pointed out several doc  
> bugs that
> have actually been in there for a long time. Anyone who was trying  
> to follow
> the examples I gave would fail because of the errors, and this  
> could have
> easily caused people evaluating the Library to turn away and think  
> it's too
> difficult to use or they just can't "get it".
>
> The new version has these issues resolved, and is much better at  
> guiding new
> users into using the Library.
>
> Why am I bringing this up? So you all can avoid this in *your*  
> application's
> documentation (assuming it is to be printed or viewed as a PDF,  
> like mine
> is).
>
> Here's a handful of simple rules that have come out of this (I'm  
> sure there
> are more, but these are the ones that "bit" me):
>
> 1) Test All Example Code
> --------------------------------
>       If you include example code in your docs, make sure you  
> *test* it
> first, ESPECIALLY if you are copying and pasting code from another  
> example
> in the same docs, or copying it from a more comprehensive script  
> that may
> have dependencies on other functions/handlers/etc.
>       This can especially become an issue when you are very  
> comfortable
> using common functions or handlers that are "always there" for you  
> (because
> of your framework, common libraries you use, etc.) that very well  
> may not be
> there in your user's hands. A good example of this is the q()  
> function I use
> that simple puts double quotes around a string:
>
> function q pWhat
>   return quote & pWhat & quote
> end q
>
>      I have used this function for many years, so it is second- 
> nature to me
> to put q() around strings I want quoted without thinking of the  
> dependency
> on the function. Hand out an example in docs that uses q() without  
> providing
> the function, and your users will get errors.
>
> 2) Check Page Numbers in TOCs
> ------------------------------------------
>      If you include a table of contents in your app's docs, make  
> sure that
> before you ship that the TOC has been updated and points to the  
> right pages.
> Nothing is more frustrating than going to an incorrect page when  
> you are
> trying to learn a new app.
>
> 3) Watch Page Breaks
> ------------------------------------------
>      I have seen too many sets of docs where code examples are  
> split by a
> page break at the inappropriate time, either leaving an "orphan" of  
> a code
> line on the next page, or worse, appearing to end properly, but  
> there's
> actually *more* code on the next page you didn't know about that's  
> critical.
>      It reminds me of the Raiders of the Lost Ark scene where Indy is
> getting the amulet translated and the bad guys only have one part  
> of it. The
> translator tells Indy that the piece he has says to make a stick  
> "ten Jamirs
> high", and Indy's about to grab the amulet and leave when the  
> translator
> says "Wait, I am not finished!" and turns it over and reads "And  
> add one
> jamir to honor the Hebrew God whose Ark this is." Had there not  
> been a break
> between the two halves... ;-)
>
> 4) Read Your Own Docs As a New User Would
> ------------------------------------------------------------
>      After you *think* you are done with the docs, print them out  
> and read
> them as if you were a new user getting this application for the  
> first time.
> Imagine you know nothing about the program and that someone you  
> respect has
> just suggested to you that you take a look at it because "it's a great
> program".  Look for all the little things that might drive you  
> crazy as a
> new user - inconsistent references, inconsistent use of text  
> styles, indexes
> that don't point to the right place, etc. I'm sure you'll find a  
> number of
> things you should change.
>
> As I said, I know there's plenty more caveats to go through, but  
> these four
> are good ones, IMHO.
>
> Just wanted to pass this along to anyone working on their own docs.  
> You'll
> never know how many people turned away from your product due to bad  
> docs,
> but if you know you have *good* docs, you can rest assured that no  
> one will
> turn away because of bad docs...
>
> :-)
>
> Ken Ray
> Sons of Thunder Software, Inc.
> Email: kray at sonsothunder.com
> Web Site: http://www.sonsothunder.com/
>
>
> _______________________________________________
> use-revolution mailing list
> use-revolution at lists.runrev.com
> Please visit this url to subscribe, unsubscribe and manage your  
> subscription preferences:
> http://lists.runrev.com/mailman/listinfo/use-revolution