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.
Thanks to John Posada, Jill Burgcha, Kris Olberg, Jo Oehrlein, Cam
Whetstone and Beth Agnew for their responses. My question was: I'm told
to interview for someone who can "document code," or could I do it and
we'll hire someone to do my work on user guides. What should I ask
management for clarification? Should I take this on?
Several folks cautioned against trying to document old, uncommented
code. It takes a programmer, and not just any, to do that, it is very
slow, and you may waste time on obsolete code. Programmers should be
documenting their own code as they work from a higher-level design.
Some writers have worked on a high-level organization of programmers'
documentation, to varying degrees of success. It seems to work best when
programmers are working from detailed functional specifications that
have been turned into detailed technical specifications.
I have queried the programming group leaders to define the level of
their documentation needs and what time they would make available to
someone. I have tried to strongly discourage them from expecting
"reverse engineering" of code from a tech writer -- they need to hire a
programmer to do that (and some programmers here have already attempted
it, with great difficulty).
Thank you all for sharing your accumulated wisdom!
> ----------
> From: John Posada[SMTP:posada -at- faxsav -dot- com]
> Sent: Wednesday, January 21, 1998 1:58 PM
> To: 'Lani Hardage'; TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU
> Subject: RE: Code documentation requirements?
>
> Lanie...
>
> 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'm in a similar environment where everyone around me speaks UNIX,
> Perl, C, etc. I guess the first question that comes to mind is: Since
> you are already doing something, would the addition of this job
> function impact everything else you are doing. I don't know what your
> workload is, but do you have the time to take on the job and do the
> one you are doing now.
>
> It appears that your company believes that there is enough to bring
> someone on and companies don't usually do that for only an incremental
> increase in workload.
>
> Another question that comes to mind. I know that my programmers are
> writing code "that you never learned in school". Much of this is
> based on many many hours of heads-down coding. To be able to document
> this type of code, it takes more than "book learning"...it takes
> knowing "why" such-and-such code is used, so it takes more than
> "learning VB and a little Basic and Fortran".
>
> My recommendation would be to bring someone in but lobby that they fit
> under you in the org chart by making the person report to you.
>
> John Posada, Technical Writer (and proud of the title)
> The world's premier Internet fax service company: The FaxSav Global
> Network
> -work http://www.faxsav.com -personal http://www.tdandw.com
> -work mailto:posada -at- faxsav -dot- com -personal mailto:john -at- tdandw -dot- com
> -work phone: 732-906-2000 X2296 -home phone: 732-291-7811
> My opinions are mine, and neither you nor my company can take credit
> for them.
>
> HEY! Are you coming to the NJ TechWriter lunch? So far, about 10
> of us are. Ask me about it.
>
>
