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.
> 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?
As I've suggested in another post, it's not the concepts of
programming that are important, but how it's used. The point isn't
to convey a knowledge of programming to every user, but to use your
knowledge to convey additional information.
To give a simple example, the Windows version of FrameMaker has a
menu item for customizing menus. However, the documentation doesn't
tell you how to set up a custom menu. Armed with the ability to read
code, you could give readers the instructions about how to make a
custom menu that made no assumptions whatsoever about their
programming knowledge, and doesn't try to teach them any.
> 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?
Of course, you can do both. My contention is that you can't do your
best possible job that way, although I grant that you can do an
adequate one, sometimes.
But to take the programming analogy: on one level, it's black box.
However, how the third-party libraries are used isn't. And, in
practice, conscientious programmers do like to probe around and find
out as much as they can about the libraries they're using.
And another problem about black box writing that just occurred to me
is that it can be hard to know that you have all the output. That's
especially true with a GUI. For example, Windows NT comes with any
number of GUI tools, but I don't know any system administrators
worth hiring who would claim that a manual that only documented the
GUI would adequately document their duties. But, a black box writer
might very well not realize this fact unless told by someone else or
until after a few complaints were received.
--
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.
