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.
Subject:Documenting code? From:geoff-h -at- MTL -dot- FERIC -dot- CA Date:Mon, 26 Jan 1998 09:19:08 -0600
Lani Hardage wrote <<I am the only techwriter doing
end-user docs, and the company wants someone to document
code. I'm supposed to interview the applicants, but
they've asked me whether I'd consider doing it.>>
I'll echo what John Posada said: if they're considering a
full-time worker, will it really be possible for you to add
that much work to your current job? I'm not optimistic,
particularly given the rest of the context:
<<What would you look for, since our company has a product
written in C, some new code in C++ (with some APIs in the
pipeline), and Visual Basic?>>
Look for one hell of a challenge. Three programming
languages, one of which (C) is famed for its ability to
produce indecipherable code? <shudder>
In addition to this relatively minor problem, I think
there's another killer that nobody's mentioned: management
is basically asking you to reverse-engineer the code to see
what it does. This is not a trivial task. You're either
going to be beating your head against a wall in hope of
enlightenment, or you'll be spending an inordinate amount
of time trying to get codeheads to stop coding long enough
to explain what they did, how they did it, what assumptions
they made while doing it, and why they did what they did.
It's a fool's errand, IMHO, and it may only be possible if
your company has enough sense to use requirements or
specification documents as the basis for enforcing some
controlled form of coding; then at least you've got a way
to look back at the specs and see what the programmer was
supposed to do.
What _would_ make sense to me is to require the programmers
to do some crude initial documentation as they do the code,
and then turn it over to you to clean up so that someone
who doesn't live inside that particular head can figure out
what the person was thinking. The programmers won't like
this at all if the ones I've worked with are typical, but I
can't see any other realistic way to do the job.
--Geoff Hart @8^{)} geoff-h -at- mtl -dot- feric -dot- ca
Disclaimer: Speaking for myself, not FERIC.
