Re: Understanding the things you document

[Thom Randolph <thom -at- HALCYON -dot- COM>]

At 10:27 PM 7/6/99 -0500, you wrote:
>With everything I've documented in the past, I have
>always understood at some level how the device or
>program worked. I'm getting the picture at my new
>job that understanding the program is secondary to
>producing the documentation. Do other writers face
>this same challenge?
>

In the group where I work, we write about large data center
installations of server software. While some of the older
writers claim they don't need to understand how the systems
work, there is a tradeoff in this that they don't always
admit.

---Impatient Executive Summary---

Basically, if you're not an SME yourself, your documentation
will require more detailed and lengthy research, and once
written will need closer review and testing by those who are,
which in turn leads to more extensive changes due to incorrect
technical details you've documented. On the other hand, being
"your own SME" can mean interactions with the other SMEs are
more "confirmations" rather than "interviews", and the stuff
you write is more likely to be accurate earlier. From every-
thing I've seen, finding and fixing problems sooner is much
less expensive than later. So, I vote for being an SME and a
writer. And, it's more fun knowing the stuff (if you're into
those kinds of things....)

But, it depends on the type of product you're writing about.
Complex innards with a simple user interface won't require as
much knowledge of the internal workings. Complex user interface
will often require more detailed knowledge.

---A Little More Detail---

When you (as a writer) closely understand the subject matter,
you are in a sense, your own SME. You may not have the insight
of the developer for the particular system, but you're 80% or
more down the road of understanding how the system works and
what it is (and more importantly is NOT) capable of doing. This
combined with an understanding of the reader's needs makes for
more effective communications.

When you do not closely understand the subject matter, your
role becomes on of active collection of the SMEs information.
You might gather this from specifications, other documentation,
SME interviews, etc. But, unless you eventually truly grok the
subject matter, you're not much more than a mouthpiece for
others' tales. I'm not trying to say that the writer doesn't add
to the value; they do, they do, they do.

What I'm saying is that without being close to the information
itself, it's difficult to discern reality from fantasy. The
fact is that the specifications don't match the product, and
the prototypes never match the specs, much less the final
product. And, the comments in the code will almost never take
mention anything but what the programmer THINKS the software
will do.

I prefer to have a solid background in the systems I'm writing
about. I even make it a point that we writers must build out
and test the systems we claim to instruct others to use. We see
a lot more of the reality than we might, and some would argue we
waste time trying to be testers. That may be. But, when the
documentation is done, we know very well exactly how the parts
interact, and can much more accurately predict what will happen
when something is changed.

It probably depends on the product complexity and the amount
of that complexity "surfaced" to the user. For instance, the
Furby animatronic toys (death to them all!) are wildly complex
internally, but that is not documented. On the other hand,
Visual Basic components might be fairly simple internally when
compared with the very detailed documentation needed to apply
them.

So, as always: "it depends".

I hope that at least my opinions are clear.
Let the flaming begin!

Best regards to all,

Thom Randolph
thom -at- halcyon -dot- com


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=