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

[Ken Ray]

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/