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 guess I just don't see how the ability to read code, here, buys you
> anything more than a good UI review would.
It's really just a case of covering all the bases.
> >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.
Purrr!
Actually, from what you've said of your background, it sounds as
though your work is far less black boxed than most writer's.
> 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.
To a large extent, you're right. You can't take what I'm saying to
the extent of paranoia; obviously, it's not practical for anyone to
read every line of code, and you have to have some trust for the
people you're working with.
But if a problem comes up, programmers are likely to open up the
other coder's work to see what's happening - especially if the other
coder isn't around. That's more or less the level of involvement
that I'm suggesting would help tech writers.
> Administration tasks are not magically exposed by looking at the source
> code, either. You need an understanding of the problem domain.
I don't think that anything I've said implies otherwise.
> 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.
GUIs are usually designed for the most common tasks done by most
users. A truism I've heard is that an GUI covers 80% of what 80% of
users want to do. I don't vouch for the exact figures, but most
programmers do assume that designing a GUI involves dumbing down. At
any rate, the point is that some functionality is likely to be
unreachable through the GUI alone. The importance of the
functionality varies from program to program, but, the point is that
you can't always know through the GUI alone.
> 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.
Very true. I'm sometimes bemused by the amount of history that some
programs contain. However, all the useful functionality is rarely
contained in the GUI. In addition, some uncommon or generally
obsolete options may be useful to mention for troubleshooting, or
for rare tasks.
>
> Reading source code is not a substitute for communication, and the ability
> to read source code should not be a prerequisite to communication.
I agree completely with the first clause, but I view the second
clause with some reservations.
I'd draw an analogy with etymology. You don't **need** to know Old
English, French and Latin to write in English, any more than you
need to read source code to write documentation. However, the more
you know about the history of English, the more nuanced and
sophisticated your writing can potentially be. In the same way, the
more you know about reading source code, the more thorough and
complete your technical documentation has the potential of being.
Similarly, you don't have an absolute need to know typography,
either, but it can often enhance your work.
I don't know - put it down to early toilet training, or something. I
simply like to have the knowledge and skills to do the best job I
possibly can, even if, realistically, I don't always have the chance
or the time to use them. I've done my share of black box writing,
and so, I suspect, have many people on the list. But it's never been
my best work. And, since I'm often a lone writer, I'm often the only
one who cares about the quality of documentation. So, I prefer to be
more self-reliant.
--
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.
