TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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
completing?
>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. 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.
