Content and Format (RE: Benchmarking Technical Documentation)

[edunn -at- transport -dot- bombardier -dot- com]

This is one of the eternal holy wars that continues to rear it ugly head on the
list at regular intervals isn't it. The discussion of how much depends on
content, how much on format, how much technical knowledge is technical enough,
how many angels can dance on the head of a pin......

I have entered this discussion before and do so again at my peril. To date I
think you're all wrong. (Now where did I put my asbestos underoos?) <vbg> At
least to a degree....

The debate seems to eternally circle around which is more important whether in
percentages or in absolutes. This time round at least there seems to be some
consensus that technical content most likely takes precedence. (Although, I
think that has always been the premise of nearly every discussion on this
subject.) A pretty document that is technically wrong is not only worthless, but
can actually be dangerous. But equally true, as presented by Kent Christensen in
the case of pre-flight requirements, a pile of technically perfect documents can
also be worthless and potentially dangerous.

And such is the art of technical writing. The combination of cold, hard, fact
and technical detail with enough design and flare to make the relevant
information jump into the users mind before they were even aware they were
reading it (or even better before they even knew they were looking for it.

There-in lies the problem with this 'debate' (and indeed many others on the
list), much of the answer depends on the situation (or audience <g>). It cannot
depend on a simple formula like the one proposed : "content is 51% and format is
49%".

To raise the corpse of another perennial monster or two, I think all the same
goes for the process vs. content/product debate and the technical knowledge
debate as well.

While Tom Murrell gives good reason why the impression of font and format freaks
or the process maniac came about, I see no reason why these stereotypes need to
continually raised amongst ourselves on a professional list. As professionals,
we should not assume that a question about style is being made because the
poster has no interest in content or technical issues. Nor should we assume that
a technical question means the writer has no interest in form or layout. It is
this knee-jerk, judgmental reaction that seems to start the "foam-at-the-mouth",
"us vs. them" debates in the first place.

If we want to battle the stereotypes, let's discuss these issues properly. It's
rarely about which is best, but what are the combinations that might be ideal
and then the balance that can be met realistically. It's no wonder engineers
think writers obsess over fonts if we accuse those in our own ranks of doing it.
It may just be that all the technical info is already there and the document
just looks like garbage.

Eric L. Dunn



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Learn about tools and technologies for user assistance developers at
The Help Technology Conference, August 21-24 in Boston, MA
Details and online registration at http://www.SolutionsEvents.com


---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.