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.
>>My job as a writer is to wrest the information the user needs from the
>> programmer, who has far more information than the user needs.
Bruce Byfield replied:
>This is one way to do it, and probably the most common way. However,
>a writer who already has the information can work faster, and with
>fewer demands on other people's time. Also, the more that you know,
>the more you can evaluate the information that you're given, and see
>what more you need to ask.
Bruce, I agree that the more the writer knows before talking to programmers,
the easier it is to get the information one needs. However, there are often
practical constraints on how much
a writer can learn before such a meeting. For example, technical doc may not
be available, and the prototype may not work well.
It's easier and more beneficial to become an expert when the writer is a
staff employee, in which case the knowledge represents an investment that
will be re-paid to the company in future projects. As a consultant working
on a project basis, the budget and schedule may constrain how much in depth
one can or ought to go.
I do not wish to imply that product knowledge is not a good thing. I'm
talking as a matter of degree here, not kind. Sometimes the greatest enemy
of the good is the perfect. Sometimes good, not perfect, is what is needed.
As a project manager, I would be pleased to have you, Bruce, on a project in
which your knowledge of the product was deep. However, I would expect that
in other projects, with tight budgets and time constraints, you might have
to depend on making limiting judgments on how deep to go.
>> If I don't waste time,
>> including listening to technical tangents by programmers, and always pull
>> the discussion back to the relevant information, I will get respect.
>Personally, I wouldn't want to define irrelevancy too narrowly here.
>Some of those tangents may be useful to you later on.
I agree that some tangents prove to be useful later and would add that
listening to some tangents can win friends among programmers, since most
people like to demonstrate their knowledge. However, time constraints again
come in here. How much time do I have with this expert and when will he
decide to cut me off to "get back to work." Did I spend most of my time
listening to tangents, however interesting?
>However, tangents can be a problem. If you listen to them, then
>programmers may assume that you know more than you do. You may be
>put in the embarrassing position of either admitting your ignorance
>or listening to long monologues :-)
I listen to them until I'm sure they ARE tangents, sometimes they just seem
to be. However, I admitting ignorance without embarrassment is essential at
times to avoid wasting time.
>> Overemphasizing writer technical understanding wastes time, in so far as
my
>> central job function of communicating with users is concerned. The trick
as
>> a writer is knowing when I know enough.
>Again, this is one way to do things, and a very common one. But why
>assume that it is the only way? I've written at the edge of my
>knowledge (the way you suggest) and I've organized my existing
>knowledge appropriately for the audience. In my experience, the
>second way is far more efficient, less nerve-wracking, and produces
>more complete and more useful manuals.
You're right. I shouldn't assume my way is the only way, but you shouldn't
assume that skillful writers can't do it the way I described and get just as
good a product without feeling nerve-wracked. It's probably a matter of
style or left-brained versus right-brained ways of doing things. My wife,
for example, is more left-brained than I, so likes the details first, out of
which emerges her understanding of the big picture. I am more right-brained,
so I want the big picture first, on which to hang the details.
>The first way is documentation triage - work that may be necessary,
>but is less than ideal. I understand that, sometimes, I may have no
>choice except to work that way. When I do, I take pride in what I
>can manage to do under restricted circumstances. But what I have a
>hard time understanding is why so many people think that that is the
>best and only way to work. I can run a seven minute mile with a
>forty pound pack on my back, but I can run a mile in well under five
>minutes if I don't handicap myself.
I like your term--documentation triage. Is it original?
>> Writers who feel we have to have as deep an understanding
>> of the system as the programmers may be indulging our personal interests
>> more than performing the art of technical writing efficiently.
>With all respect, I think you're only looking at the short term.
>Knowing just enough to write the necessary manual may be more
>efficient in the short term. However, if you ever work in a similar
>field again, or even if you're simply good at making connections
>between different bodies of knowledge, nothing you learn will be
>wasted.
Look, Bruce, you are on the side of the angels here--arguing on the side of
knowledge. Who can disagree that knowledge is a good thing long-term. If
every tech writer knew ten programming languages before they wrote the first
line, that ?might? be a good thing, but it's not very practical. I think
it's far more important to have in-depth knowledge about the industry for
which we are writing than it is to have programmer-level knowledge about the
technology. This industry-level knowledge is transferable, even for a
consultant. It also assures that examples and task organization are on
target for the audience, which makes for a more usable manual.
After a writer has done doc for few systems, he/she realizes that the
technical structure of many them is similar. This kind of technical
knowledge is very useful in helping the writer to understand new systems
rapidly and in formulating differentiating questions. Again I ask, does one
have to know everything before one writes anything? I don't think so, unless
one is afraid ever to be wrong.
>Anyway, a bit of indulgence in work-related material can keep you
>interested and motivated. So long as the manual is delivered
>complete and on time, where's the harm?
Agreed, about indulgence--following one's nose--so long as the work product
ends up being complete, accurate, on-time, and usable.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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 an
anonymous satisfied subscriber since 1994.
---
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.
