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: [EMAIL PROTECTED]
Web Site: http://www.sonsothunder.com/
_______________________________________________
use-revolution mailing list
[email protected]
Please visit this url to subscribe, unsubscribe and manage your
subscription preferences:
http://lists.runrev.com/mailman/listinfo/use-revolution
_______________________________________________
use-revolution mailing list
[email protected]
Please visit this url to subscribe, unsubscribe and manage your subscription
preferences:
http://lists.runrev.com/mailman/listinfo/use-revolution
