Re: Have to know Programming to be able to write about it? -- NO

["Gary S. Callison" <huey -at- interaccess -dot- com>]

On Thu, 27 Feb 2003, chris -dot- gooch -at- lightworkdesign -dot- com (Chris Gooch) wrote:
> Beth wrote:
>> The expert is often the worst person to write about their subject, 
>> because they no longer see it with the naivete of the new user.
>> Hence the manuals that leave out crucial steps because "tsk, everyone 
>> _knows_ you're supposed to do X before Y". 
> My view is that the ability to know your subject, _whilst at
> the same time remembering that your reader does not know
> so much about the subject yet_, is precisely the skill of
> a good writer -- being able to put yourself in your reader's
> shoes.

That's the problem of knowing your audience. Here's a real-world example: 

I had to write a procedure for maintenance of a cluster of IVR telephony
boxes. There are two user groups: people who work with these machines
every day and know them intimately, and people who work in a different
group, know nothing about these machines, but may be called to do
something in case of emergency. 

The procedure for the first group was one page and consisted entirely of
a table that showed how switch port numbers mapped to machines. Everyone
in the first group could just look at that table and know that "if I want
to take down box X, I need to busy out trunkgroup Y", had all of the tools
and understanding to do that, and could do all of the minor supporting
tasks that were routine for them. 

The procedure for the second group was around fifteen pages long, and had
a lot of references to external documents, like so: 

1. Log in to the radius server by clicking on the radius client icon. If
you do not have a radius client icon, see <URL> "How to install the radius
client". 

2. The first window that appears will prompt you for your radius logonid
and password. If you do not have a radius password, you will be unable to
complete this procedure for at least 24 hours, so you should page
the oncall switch tech if you have an immediate concern. Also, see <URL>
"Applying for a radius password".

3. Once you have logged in to the radius server, the next window that
appears will be a list of phoneswitches. Select the local phoneswitch and
click LOGON.

4. The radius client will now prompt you to  enter your switch logonid and
password. If you do not have switch passwords, again you will be unable to
complete this procedure for at least 24 hours, so you should page
the oncall switch tech if you have an immediate concern. Also, see <URL>
"Applying for switch passwords". 

5. Once you are in the switch, type "DSKUT<ENTER>"...etc. 

Now, it's impossible to write the first document without knowing what the
experienced users really need to know. There's two ways to get that
knowledge: either become an experienced user, or to ask one. The second
document, anybody can write. All you have to do is get someone to show you
what has to be done to accomplish the procedure, write down everything in
the smallest detail, and then anyone can follow in your footsteps and do
just what you did. Neither documents require an expert to write, merely
that an SME be available to assist in the writing process. 

However, it is expedient if the writer is also the expert - you can
produce documents more quickly, without asking anyone else for anything,
and assuming you are aware of the needs of your audience, share a
significant portion of your level of expertise with everyone else around
you. This is limited only by the depth and number of contingencies you can
document. Which would a telco rather have, a skilled telephony tech, a
skilled tech writer, or someone who can do both? [1]

A technical writer doesn't have to be an expert to produce documentation.
They don't even have to become one in many instances, although things like
software requirements specifications do require an intimate understanding
of the product, from business rules to UI. But it is in the TW's best
interest to become as skilled in as many different areas they are likely
to need to produce doc for as they can.

[1] It's a trick question. All three were laid off. I was 'both', though.

-- 
Huey


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

LAST CHANCE for this steal of a deal! Purchase RoboHelp X3 by February 28
and receive $100 mail-in rebate and FREE WebHelp Merge Module ($339 value)!
RoboHelp, the Industry Standard in Help Authoring, has won over 55 industry
awards. For more information please visit: http://www.ehelp.com/techwr-l2.
 

"RoboHelp X3 is simply remarkable." - George Bell, Techno-Vision Systems


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