Re: Managing Engineers - black box writing

Subject: Re: Managing Engineers - black box writing
From: mpriestl -at- ca -dot- ibm -dot- com
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 27 Nov 2000 15:29:48 -0500

Bruce Byfield writes:

>While I tend to agree with Andrew's position, you can write using
>the black box model.
>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.

This sounds very incomplete. I'd hope for concepts, tasks, relevant
reference information, a "getting started" tutorial in printable format, at
least an index and hopefully a search engine, integrated help and
knowledge-base articles, and links to further reading, training
opportunities, FAQs or tech support on the web, and feedback on both docs
and program. All of which could be provided by a writer who didn't know
what "referential integrity" meant, let alone what code the program
implements to support it.

To go the next level down, can you tell me what language DB2 is written in
by reading its User's Guide? Can you tell me what application development
tools the developers used? Does it bother you that this information is
missing? What task does this missing information prevent you from

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

I'd be helped by some concrete examples here. Unless you're documenting an
open-source product and expect at least some of your users to be getting
right into the guts of the program, what purpose is served by telling them
about things they can't change and that have nothing to do with the tasks
they want to accomplish? Is a tutorial on string (rather, char array)
programming in C appropriate for a FrameMaker manual? Is it important
knowledge for the writer of a FrameMaker manual?

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

Anyone who does object-oriented programming with a third-party class
library (like, say, Sun's JDK, IBM's OpenClass, or MSFT's Foundation
Classes) is engaged in black-box programming.

If you can program using the black-box model, why can't you write using it?

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

Speaking on my own behalf,
Michael Priestley
IBM Toronto Lab

Develop HTML-based Help with Macromedia Dreamweaver! (STC Discount.)
**NEW DATE/LOCATION!** January 16-17, 2001, New York, NY. or 800-646-9989.

Sponsored by SOLUTIONS, Conferences and Seminars for Communicators
Publications Management Clinic, TECH*COMM 2001 Conference, and more 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 for more resources and info.

Previous by Author: Re: Managing Engineers (long)
Next by Author: Re: Managing Engineers (long)
Previous by Thread: Re: Managing Engineers - black box writing
Next by Thread: Re: Managing Engineers - black box writing

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

Sponsored Ads

Sponsored Ads