Re: Managing Engineers - black box writing

[mpriestl -at- ca -dot- ibm -dot- com]

Bruce Byfield wrote:

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

I guess I just don't see how the ability to read code, here, buys you
anything more than a good UI review would. I'd think this functionality
would be easier to discover, play around with, and later explain by using
the tool, ather than by looking at a bunch of source files. This may just
be a difference in working styles, but I certainly don't think my style is
inferior. Reading code may even be misleading, inasmuch as you may discover
function that is included in the code base but being excluded at build time
(for example, because the function was included too late in the product
cycle to be thoroughly tested).

I'm not saying you _shouldn't_ read code, just that you shouldn't _have_
to. There are other ways to fix communication problems besides learning
Java, and learning Java on its own won't fix the problem anyway.

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

Bruce Byfield replied:

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

Why thank you. I'm pleased that, sight unseen, you will grant that my docs
might be adequate.

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

On a large software development team, every developer treats other
developer's components as black boxes. Encapsulation is a large part of the
point of object-oriented development. This is a virtue, not a flaw.

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

Administration tasks are not magically exposed by looking at the source
code, either. You need an understanding of the problem domain. The user
interface is generally more task-oriented than the application, and the
docs are hopefully even more task-oriented than the GUI. I don't think you
can reasonably expect to get more task-orientedness by looking at a level
of the application that is by definition more distant from the user
experience.

I don't think a "black box" writer is any more susceptible to error at the
command line level either - no matter what, you need to be talking to your
developers and reading (if they exist) design documents. For example, you
may find command-line options in the source code that are not exposed in
-help because they are experimental, or deprecated to the point of
obsolescence but still included to avoid breaking one company's batch
files.

Reading source code is not a substitute for communication, and the ability
to read source code should not be a prerequisite to communication.

That said, it's a handy skill, but I certainly wouldn't say that it's
essential to good tech-comm, except where you have an _audience_ (as
opposed to a developer) who requires 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.