Re: Do users actually read READ.ME files?

["Steven J. Owens" <puff -at- NETCOM -dot- COM>]

Trevor Grayling writes:
> I've seen a number of studies (and conducted my own) that indicate that
> software users frequently ignore manuals and even online help.  I suspect --
> but have no data -- that the same can be said for the READ.ME files that
> accompany most software releases.

Obviously, this is much dependent upon your target audience; I know
I'm atypical any way you slice it:

     From a techie point of view, I'm weird because almost always give
     the docs a quick look before starting.

     From a non-techie point of view, I'm weird because I'm extremely
     technical and I can usually figure things out for myself.

If your product is a shrink-wrapped, off-the-shelf, auto-installed
package for extreme end users, they probably won't even be able to
figure out that there *is* a README file, let alone read it.  On the
other hand, a techie user will probably look for a readme file first
thing, unless they've been trained out of it by the past five or ten
years of useless readme files full of fluff or excess minutia.

My advice is that you should always have a README file, but don't
count on your users to read it (unless you pop it open at the end of
the installation).  How much energy you want to put into it depends on
how likely your users are to read it.  What you want to put in it,
however, is a little more straightforward:

A README file is (and is supposed to be) extremely simple in format
(text only, very linear) and structure.  In general, the README file's
job is to be a starting point; it is the most obvious place to start
looking if you have no clue what these files are or why they're in the
directory.  It should be short, general, and to the point.  This is
what this is, this is what it's about, this is where to find the
information you may need.  Here's how to contact us.

Don't make any assumptions in the README - it's incredibly annoying to
crack open the README on a mystery application and find lots of
cryptic references to things that assume you know what the heck the
thing is, and what it's for.

If the application scope is narrow enough that you can include a
*really* brief overview and "here's how to get started", but only a
paragraph or three.

A README file is also a good place to stick last-minute information,
*because* it's so limited in format that you can just type in a few
paragraphs and that's it.  If you're only adding a few details, you
can get away with this, but if the extraneous information starts to
swell or accrue (say, behind two pages of conventional text
i.e. 100-150 lines of 80 character-wide text) then stick the
extraneous information in a separate file and point to it from the
README doc: "A list of reported issues and changes to resolve them is
in ISSUES.txt; a general list of changes is in CHANGES.txt."

Lastly, always include basic contact info in the README (kind of like
the "about" box).

A readme file is like a resume; you can't count on the user reading
it, and if they do, you can count on them just skimming it quickly
before they get on with using the application.  Maybe you don't have
to obey the resume 1-page rule as strictly, but that should be your
mindset.

Steven J. Owens
puff -at- netcom -dot- com

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=