Re: Managing Engineers - black box writing

Subject: Re: Managing Engineers - black box writing
From: Bruce Byfield <bbyfield -at- axionet -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 27 Nov 2000 11:39:32 -0800

Andrew Plato wrote:
>
> That is EXCEEDINGLY relevant. Knowing these technologies gives you an intimate
> understanding of how the product works. This lets you anticipate issues,
> concepts, and potential ideosyncracies.
>
> I find it disturbingly humorous that you would defend technological ignorance
> as an acceptable and endorsable modus operandi for people tasked for TECHNICAL
> communications.
>

While I tend to agree with Andrew's position, you can write using
the black box model.

As most people probably know, a black box is an area whose inner
workings you know nothing about. However, you do know what goes into
it and what comes out. Working with this model, you don't need to
know all the inner workings of a program that you're documenting,
but you do need to know how to access the inner workings, and what
they produce. For example, if you're documenting a database program,
you may be able to get away with instructions about how to open the
program and a list of the required fields, then a description of
possible results: say, error tables or reports.

Of course, the more technical your audience is, the less likely that
this approach will produce satisfactory documentation. You are also
apt to miss details. And, so far as I'm concerned, the black box
model is very unsatisfactory if you have much curiosity or any pride
in your work. I know one engineer who, faced with an influx of new
technology and the likelihood of having to do black box engineering
(since he would retire before he could possibly master the new
technology) took early retirement with smaller benefits rather than
- as he saw it - compromise his professional integrity. He then went
on to a very successful second career as a science fiction writer.

I respect his decision very much, and I wish that more tech writers
felt the same way. I think that far too many of us settle for black
box writing - not just as an expediency in an emergency, but as the
normal way of doing things.


--
Bruce Byfield, Outlaw Communications
Contributing Editor, Maximum Linux
604.421.7189 bbyfield -at- axionet -dot- com

"This is the hour when the city turns blue,
This is the time of the lost and found,
They've loosed the nutters in the Underground,
Everything's far and nothing is true."
- Oysterband, "The Lost and Found"

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY.
http://www.weisner.com/training/dreamweaver_help.htm or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more
http://www.SolutionsEvents.com or 800-448-4230

---
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.


Previous by Author: Re: FWD: Finding a recruiter
Next by Author: Re: Managing Engineers (long)
Previous by Thread: Going from RoboHelp to RoboHelpHTML
Next by Thread: Re: Managing Engineers - black box writing


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


Sponsored Ads