Fw: Vanishing buttons

[Suzanne Gerrior <suzanne -at- JAZZMAIL -dot- COM>]

I have forwarded this response (at Geoff's request) to my question
concerning what to do when an important button is removed from the interface
and  the documentation has gone to the printer.

Many thanks to everyone who responded. I included a Read Me page on top of
the documentation.
s

Suzanne Gerrior
Documentation Specialist
Jazz Media Network
Tel: (514) 931-7009, ext. 255
Fax: (514) 931-9495
suzanne -at- jazzmail -dot- com




Greets!

Please forward to techwr-l for further elaboration and refinement; I
can't post directly. Thanks. See you at the meeting Tuesday?

--Geoff
***********
Suzanne Gerrior wondered what to do when a button has been removed
from the interface after you've already printed the documentation. My
first reaction is like yours: take a well-deserved vacation, then
come back and let the developers explain to your managers why the
product shipped with changes after the interface freeze. However,
since you've probably still got to live with these people after...

Best bet is, as you proposed, to include an insert that will be
shrinkwrapped right atop the manual. (Readme files aren't a safe
way to ensure your audience spots the change; _I_ read them, but
I'm a compugeek and have other serious abnormalities. <g>)
Prominently warn your audience of the change, explain why it was done
(if possible) so as to make the change seem more reasonable, and
explain what the implications are for the documentation and use of
the product. If you must revise substantial parts of the docs as a
result, it's probably better to reprint those sections in their
entirety. (If you've produced a 3-ring binder documentation set, this
will work well, particularly if you can get the developers to do the
grunt work of inserting the corrected pages; if it's a perfect bound
manual, at least people can use the insert in place of the bound
pages without having to write corrections in their manual or flip
back and forth between an erratum sheet and the manual.

Most important: When you're done, sit down with the project manager
and provide an estimate of what the stupid last-minute tweak just
cost (in printing $ and staff time) and see how you can make sure it
doesn't happen again. It probably will, but at least then you can
refer smugly back to your agreement and ask why they figured that
adhering to it was optional. Remind them that "service releases" were
designed specifically to handle last-minute tweaks, and that the
product should never have gotten to the shipping stage if there were
any remaining concerns serious enough to make them revise the
interface.

One final comment: There seems to be a prevailing practice in the
industry that documentation goes to the printer several weeks before
the software goes to be duplicated onto CD's or diskettes. I'm not
sure why this is, and would be curious to find out. In my business
(scientific publishing), I've always had roughly 2-week turnaround on
printing jobs without putting any pressure on the printer whatsoever;
I can push the printer to do better if the deadline is really
serious. In fact, for our own most recent software release, the docs
and the software went out for duplication simultaneously. For large
releases, both can go to a single-source packager who will dupe the
disks, print the manual, and package everything for you. One of our
local suppliers claims this would even save us time and money,
something I'll investigate for the next release.
--Geoff Hart @8^{)}
geoff-h -at- mtl -dot- feric -dot- ca

Hart's corollary to Murphy's law: "Occasionally, things really do work
right."