summary-chaptrs w/o # and manual updates (long)

Subject: summary-chaptrs w/o # and manual updates (long)
From: "McIntosh, Cathleen" <Cathleen -dot- McIntosh -at- vistacpg -dot- com>
To: "TECHWR-L digest (E-mail)" <techwr-l -at- lists -dot- raycomm -dot- com>, "ezra (E-mail)" <ezra -at- Resonate -dot- com>, "FrameUsers. com FrameMaker Discussion List digest (E-mail)" <framers -at- lists -dot- frameusers -dot- com>
Date: Mon, 20 Mar 2000 18:05:44 -0600

Thank you very much to everyone who responded to my inquiries about creating
a manual without chapter numbering and delivering updated manuals. Responses
to each inquiry are summarized separately. The summaries are followed by the
planned course of action.

Delivering Updates: Not everyone agreed on when or how updates should be
provided, but the general consensus was that it all depends on the company's
policy. Because many of us work for smaller or newer companies, where
policies haven't been clearly defined, the following guidelines (as they
were suggested to me) may be helpful.

If users are viewing PDFs on-line, then send a whole new PDF file,
regardless of the scope of the changes, and provide info on the changes.
If users are going to print PDFs for insertion in a binder, then send a
whole new PDF file if changes affect 25 % of the manual or more. If less
than 25% has been affected, provide new front matter, indexes, tables of
contents, release notes for the new info, and instructions on how to remove
and replace the sections within the manual. However, it was noted that many
users do not actually perform the remove and replace procedures and that
asking users to remove and replace over 60% of the manual is unkind.

At my company, our update policy has finally been defined within the
contract to state that updates will be provided via PDF file only. So at
least I don't have to bother with printing things out and mailing them, etc.
Users can take the pdf and do with it what they will.

Manuals without Chapter Numbers: My initial post asked if anyone had
created a manual that did not use chapter numbers. I asked for reactions to
the idea of using letters and names for the chapters, or sections, rather
than numbers. The reason to eliminate numbering would be to facilitate the
updating process when multiple clients receive different versions of a book.
Many of you--especially Framers--politely reminded me that Frame lets you
set up multiple books to reference the same files in different ways. I agree
that this is a great way to go. However, it still may be a bit cumbersome if
ten clients are receiving documentation updates at the same time, and all
books must be regenerated.

I did receive responses from people who have tried this before with good
results. It is especially handy because anyone can insert the section into
their binder, and the section won't seem out of place. Of course, if we go
on the assumption or fact that users won't insert the updates in the binder,
then this suggestion is really no better than any. And of course, if we are
going to generate a whole new PDF because we assume or know that it will be
viewed online only, then there is really no need to omit chapter numbering.

Result: At this time, we have not decided on whether or not to do away with
chapter numbers in place of an alpha system. It seems to me, that the alpha
system does not hold many advantages over the numeric system. Please contact
me off list if you would like me to let you know what we do decide. As for
delivering updates, I'll be happily generating and sending PDFs to clients
periodically, along with a What's new section that briefly describes new
functionality and directs users to related information in the guide.

Thanks again for your contributions,

Cathleen McIntosh
cathleen -dot- mcintosh -at- vistacpg -dot- com

Previous by Author: delivering updates: WAS manuals w/o chapter #'s
Next by Author: TOC disappearing in help project
Previous by Thread: GNU C++ Compiler
Next by Thread: Edward Tufte Course on Presenting Data and Info-book recommendations

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads