From: 3037mpas@ucsbuxa.ucsb.edu (Michael D. Wells)
Newsgroups: comp.lang.c,comp.windows.ms,comp.org.acm,comp.org.eff.talk
Subject: Documentation Questionnaire Responses
Keywords: documentation manual questionnaire summary response
Date: 27 Jul 92 00:53:55 GMT
Followup-To: comp.lang.c
Distribution: comp



Here it is -- the long-awaited response to the documentation
questionnaire.  For those of you who didn't see the original
post, I requested input on how computer documentation is
used, and what people prefer.  The questions were very
general, and did not assume any particular type of hardware,
software, or user, although the results are naturally biased
toward the type of person that uses Internet and reads the 
targeted newsgroups.

Since there was some confusion before, I should clarify what
I mean by "user".  I'm using the term in the general sense, and 
not in the hacker sense of someone who is totally clueless about 
computers.

There were 68 responses that answered at least one question.

>1.  Binding:  What kind of binding do you prefer?  What size 
>    pages?  Any special requirements?  Pet peeves?  Some 
>    possibilities:  3-ring binders, spiral binding, perfect binding 
>    (regular paperback), Otabinding (like perfect, but lies flat 
>    more easily).  Optionally, spiral-bound manuals can have a 
>    spine, which allows you to read the title from the shelf, but 
>    which doesn't interfere with the way the manual opens.

Two issues stood out as most important:  sturdiness and the ability 
of the manual to lie flat on the desk when open.  The results were 
as follows:

ISSUE					TIMES MENTIONED
Lies flat when open				31
Doesn't fall apart with use			28
Can accept change pages				11
Pages turn easily				 9
Title can be read on shelf			 5
Stands upright on shelf				 5
Can be photocopied easily (!)			 4
Binding can be replaced				 2
Can fold all the way back			 2
Wipes clean easily				 2
Doesn't get tangled in things			 2
Tabs can be inserted				 1
Can stack on desk when open			 1
Can be customized				 1
Uses minimum shelf space			 1
Writing space in margins			 1
Not too heavy					 1

While some of these concerns rule out certain types of bindings
(only 3-rings accept change pages, and only wire-ring folds all
the way back), there was substantial disagreement over which
bindings best met the requirements.

TYPE			FOR           AGAINST
3-ring binders		21		15
Wire ring (any variety)	20		10
Perfect			 9		 8
Otabinding		 6		 0
Other			 3		 3

Wire ring binding is a more accurate term for the most common
type of "spiral" binding.

I discounted a couple votes for otabinding, on the grounds that
they were going strictly by my description of it, and hadn't 
actually used it.

Most of the people that preferred 3-ring binders also preferred
8 1/2" x 11" paper, or something about that size, like A4.  The
point was to have a standard size for easy photocopying, 
rebinding, etc.  Over all, though, there were 8 people who
wanted this paper size, and 15 who preferred something around
6" x 9".  I assume the other 45 people don't care that much.

>2.  Page numbering:  Do you prefer sequential numbering 
>    through the entire manual or numbering by chapters (so 
>    that the third page in chapter eight would be 8-3)?  Are there 
>    other possibilities?

This one was easier.  30 people wanted sequential numbering
and 14 wanted chapter-page numbering.  2 people wanted both.
3 wanted chapter-page-section numbering, making it easier to 
look something up.  In general, though, the supporters of 
sequential numbering were *much* more emphatic.

>3.  Do you use manuals primarily as reference when you're 
>    already stuck, or as a teaching aid to help you learn the 
>    product?  Do you use them at all?

23 people used the manual only when stuck, 19 as both a
tutorial and reference, and 8 people said they actually READ 
THROUGH THE WHOLE MANUAL before using the product.  No, really!
They said that!  Then they use it only for reference.  6 people
said it depends entirely on the product, and one person said he
doesn't use them at all.

Almost all of those who use both tutorial and reference
thought these should be separate manuals, to avoid having
to constantly flip through the tutorial after learning the 
program.

>4.  How extensive should on-line help be?  Should it be an 
>    abbreviated version of the manual or should they take 
>    different approaches (for example, a strict reference guide 
>    on-line and a more tutorial-oriented approach for the manuals)?

40 people thought on-line help should be strictly reference, 
and most of these thought it should be kept brief, to avoid
wasting disk space and to make it easier to find what you
want.  However, there were 12 votes to put the whole manual
on line.

There were 7 suggestions for an on-line tutorial, but mostly
for other people who are new to computers.  5 people wanted 
examples, 2 wanted a "cookbook" to show how to accomplish 
common tasks, 2 wanted greppable text files, and 4 thought 
on-line help was a complete waste of time and disk space.

Those that didn't like on-line help complained that you can't 
take it home with you to read at your leisure.  Those that
preferred it said it's easier than trying to track down the 
manual because people are always taking it home with them!

>5.  What would you most like to see in software documentation?  
>    What would you most like to remove?

In this whole thing there was one clear Mandate From The People.
Although I did not mention indexes, I received 32 responses
telling me how important the index is.  Some of them went on
*at* *great* *length*.  Completeness and accuracy were the main
issues.

Other concerns:  More and better examples (12), use of color (2),
professional typography (2), a light tone with some humor (3), 
diagrams and overviews (2), and those marks on the edge of the
page that serve as tabs in bound books (2).

This just scratches the surface.  There were a lot of good 
suggestions, including complete structure outlines for manual
sets, and some fairly detailed ascii drawings.

Several of you asked what company I work for.  I work for
Softool Corporation in Santa Barbara, CA.  We make a software 
configuration management program for UNIX, VMS, MVS, and 
PC's.  We currently use 3-ring binders with chapter-page 
numbering and questionable indexes. 

Thanks to all who responded.  This is *very* helpful
information.

Mike Wells
3037mpas@ucsbuxa.ucsb.edu

Newsgroups: comp.lang.c