Re: Perfect Documentation

[Steve Gray <sagray -at- AMP -dot- COM>]

Joe Fockler writes:

> Do you have any thoughts and ideas as to what makes a manual or document
> set great?

Check with your users! Their opinions should guide you, first and foremost.
If possible, gather some of your "customers" together, and discuss how
they use the documents, and what they'd like to see.

> Who sets the standard to emulate?

I prefer innovation to emulation. There's always a *better* way to do it!

> What is the most effective approach for a consistent look for these two
> different markets?

Perhaps a standard on the document appearance (margins, typestyle, logos,
and such) should be enough for this. If the users are different, and if
require different styles, then make two different documents.

(Here's where I switch to philosophical overdrive...) Writers in my office
struggle with the old paradox. A style guide, or even a document-content
specification, is supposed to ensure quality by enforcing consistency.
But consistency doesn't ensure that the document will meet the customer's
needs. I'm probably a bit heretical about it, but I prefer to work
without a hard-and-fast style manual. Sure, there are style conventions
to follow, but I refuse to be chained to 'em! (Dropping back to impulse...)


Finally, a question for you concerning your document size: Does your group
produce documents for non-U.S. customers?

----------------------------------------------------
 Steve Gray                          sagray -at- amp -dot- com
 Corp Stds & Tech Pubs
 AMP Incorporated, Harrisburg, PA    (717) 780-4393
----------------------------------------------------