doc models wanted (summary)

["Bonni J. Graham" <bgraham -at- ELECTRICITI -dot- COM>]

Sue and all,

Since I have an email address for you now, let me simply compile the
messages I got for you and send them this way.

At the beginning of the week, I asked for doc models for a friend of mine.
I said I'd post a summary, and here it is:

ORIGINAL REQUEST:
She's in the process of putting together a manual for extremely
naive end-users who want as little detail as possible in the book.  What
she's planning on doing is creating a two-page spread layout, where each
spread contains the entire set of information about a topic (i.e., one
spread=one topic).  She'd like to hear from anyone who's tried this about
what worked and what didn't.  She'd also like to know if anyone has even
seen a book like this, and what book it was, so she can go look at it.

RESPONSES:
Basically, if someone simply recommended the book listed below, I
summarized it into the following reference.  If he or she provided
additional information, it appears in a list below the book reference,
separated by asterisks. I've included the respondent's email address at the
end of each detailed post so you can contact that person directly for more
information.

6 people recommended:

How to Write Usable User Documentation by Edmond H. Weiss, Oryx Press, 1991

Doug Engstrom provided ordering info:
Call 1-800-279-ORYX

***
I'm not clear what the topics would be, but I have contracted with
a wonderful group of Carnegie Mellon alumnae who have a group called
CarnegieWorks (in Pittsburgh).   They have created for me manuals for
standard software applications (WordPerfect, Lotus, Windows, etc.) in the
format that you mention, and they work very well for our beginning end
users
(nurses, physicians, new PC users on our 1000 device Novell network).  If
you
would like more information about them, or copies of their work (with their
permission, of course) let me know.
From: NancyLW -at- aol -dot- com

***
We at SOLUTIONS have been using the two page modular
documentation/structured documentation (call it what you will) approach
for 10 years. We're true disciples of Ed Weiss' methods, as well as
friends and co-workers of his (though that came later). We've also been
teaching courses on this methodology for years.

I'd be happy to talk with Sue about the approach and to send/fax her
pages from lots of different types of documents that use the 2-page
spread. In a nutshell:

Advantages:

- Everything on a topic is immediately accessible and visible.
- You're forced to think through your book's structure early, which makes
  for a better end product.
- It's really easy to index and generate a TOC!
- You'll use more graphics that you would otherwise.
- Readers get really comfortable with the structure.
- It's very easy to reorder, reorganize, or update the document.

Disadvantages:

- Not everything fits neatly into 2-page chunks. So it can be artificial.
  But any method of presenting information is artificial in some way.
- You can find yourself really struggling to make information fit on
  a page or two. But it makes your writing really concise, which is good.
- Your page numbers may start on the left instead of the right, which
  always throws off printers and copy people. You have to give very
  specific instructions.

I could go on proselytizing all day, since I'm truly one of the converted.

Paula Berger
SOLUTIONS, Inc.
(the people who send out those red course brochures)
solution -at- world -dot- std -dot- com

***
Of course, Hughes Aircraft pioneered this design shortly after WW-II.
It lay dormant for years, used only in narrow applications.  In the
mid-eighties more and more companies began resurrecting it as a doc
design format.  Now even the DoD accepts modular design proposals;
Raytheon was instrumental in accomplishing that.

<Snip--ref to Weiss book>You might also try, John Brockmann's _Writing
Better User
Documentation_ published by Wiley.  The book is a victim of impenetrable
layout, but there is good information there.

Best of luck,

Charles Sides
csides -at- FSCVAX -dot- FSC -dot- MASS -dot- EDU

***
Sounds like she is re-inventing a part of Information Mapping(TM), though
I've never been through the indoctrination, so I don't know much about it.

My only comment is that if users want as little detail as possible, she may
find that filling two pages on every topic means she has to streeeeetch
things that would normally require only one page to explain. Of course,
I don't know the topics she is dealing with, so that may not be true.

Users who want as little detail as possible probably also want to see as
few pages as possible.

See ya,

Yvonne DeGraw
yvonne -at- smartstar -dot- com

***
<snip--ref to Weiss book>

I talked to Mr. Weiss to confirm the ordering information, and he
recommended the Que Easy series of reference books, Marian (spelling
uncertain) Graphics series of intro books, and the tutorial sections of
MicroGraphix manuals as examples of successful two-page spread formats.

I used the format when I worked for Farm Business Software Systems in
Aledo, IL. I found that I did get a little tight on space in some cases,
and moved some written information (usually definitions of screen elements)
to the facing page, which is supposed to be reserved for graphics.  I also
found it impossible to do the full-manual "walk-through" he recommends;
the manuals were too big and staff time was too fragmented.  However, I
did mini walk-throughs of individual section groups.

Mr. Weiss said if you want to contact him directly, he could be reached at
his 'Net address: EdWeiss -at- AOL -dot- COM  (I have his permission to post his
address to the list.)

Good luck on the project,

Doug
ENGSTROMDD -at- phibred -dot- com

***

Bonni -- Sue's client sounds similar to one I had last year; the
application was fairly complex, but the users didn't want to read a lot
of documentation.  The solution that worked for this particular client
was to create two or three one-page Quick Reference Guides for the major
processes in the application (the ones they would use the most) and put
the detailed and supplementary info into the manual (a user's guide, in
this case).  The one-page Quick Reference Guides were basically tables,
with screen names shown as column headings and the actions shown below;
they were such a big hit that the client had them laminated, and users
attached them somewhere in their workstations.  They were handy "cheat
sheets."  Sorry ... I can't send samples to you ... they're boxed up
somewhere in storage.

Hope this helps.  <snip>

TTFN ....  Lori (Lathrop)
76620 -dot- 456 -at- compuserve -dot- com

***
One of the FrameMaker manuals is set up as charts of keystrokes.  I have
forgotten the name of the manual -- it was one of the set of four my
ex-company received when we purchased Frame for Windows 4.0.  Although the
manual was designed as a quick reference, I was thinking of using its
format for my ex-company's naive users who want just the keystrokes without
the explanations.  The manual is wider than long and offers a roomy spread.
Sue might benefit from examining the manual.

I look forward to reading about the responses you will receive.<snip>

Marilyn Gelman
gelman -at- sun490 -dot- fdu -dot- edu

***
Hello,

Tell Sue Gallagher I recommend taking a look at _Danny Goodman's
Macintosh Handbook_, Bantam Books, 1992. While it isn't exactly like
Sue's page design, it is close. Its strong point is that it is the
closest page layout I've seen to hypertext. Header diagrams
show you precisely where you are within the book, and well placed cross-
references tell you where to find related information. Also, each page
contains loads of information for novices, regular users, and even
advanced users.

I hope that helps,

Marc Paquette   paquette -at- metrowerks -dot- ca
Technical Publications Metrowerks Inc.

***
<Snip   ref to Weiss book>

I've used this approach in some recent work. The problems arise
when a topic doesn't need two pages and you end up with blank pages and
when
topics need more than two pages. Not everything is chunkable, but it
depends on
the type of book. I ran into problems with command descriptions that run on

for several pages and can't really be chunked.

But, in general, I think it is a good approach and good luck to her.

-----------------------------------
Fred Wersan
Bull HN Information Systems
MA30/807
300 Concord Rd.
Billerica, Mass. 01821
508-294-2322
wersan -at- zeus -dot- ma30 -dot- bull -dot- com

***
Years ago, we did that kind of thing for all Mac manuals; the original idea
was that the two-page spread would be a  poster, so everything about a
subject got crammed in there, in six or eight columns.  For users, it was
great.  Writers moaned so loudly that Apple finally said, "OK, so let the
text run over."  Immediately, people had trouble finding where stuff
started and ended.

We also retrofitted some Apple II manuals, notably the Appleworks manual in
the same style.  I think it's great.

But communal pressure from other writers takes its toll, so I haven't seen
many people using in consumer manuals.  I believe Boeing does this.  Also ,
check with the Info Mapping folks; their templates encourage this approach.

Best,

Jonathan Price
Communication Circle
918 La Senda, NW
Albuquerque, NM 87107
JonPrice -at- aol -dot- com

***
THANKS TO:
Paula Berger
Dorothy Champlin
Yvonne DeGraw
Doug Engstrom
Susan Fowler
Ken Gadomski
Marilyn Gelman
Lori Lathrop
Nancy LW
Marc Paquette
Jonathan Price
Charles Sides
Fred Wersan

Bonni Graham
Manual Labour
Director, Region 8 Conference
bgraham -at- electriciti -dot- com