SUMMARY: Code documentation requirements

Subject: SUMMARY: Code documentation requirements
From: Lani Hardage <lhardage -at- RMTECH -dot- COM>
Date: Fri, 23 Jan 1998 08:40:42 -0800

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!

Lani Hardage
Technical Writer
Risk Management Technologies
lhardage -at- rmtech -dot- com


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




Previous by Author: Code documentation requirements?
Next by Author: FOLLOWUP: code documentation
Previous by Thread: 11 x 17 drawings in PDF files (WAS: Relative Costs of Print and Online Documents)
Next by Thread: Gender and Technical Communication


What this post helpful? Share it with friends and colleagues:


Sponsored Ads