Re: Code documentation requirements?

[Beth Agnew <bagnew -at- INSYSTEMS -dot- COM>]

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.
>
> 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?
>
> I'm learning VB and have coded a little (Basic and Fortran) myself but
> never documented code. Would it be better for me to learn on the job,
> since most of our applicants want to do end-user documentation, or is it
> too hard to learn on the job? What questions do I need to ask of
> management?

I think this is a VERY BAD IDEA. People who write code should document
their code. I have no sympathy for developers/programmers who "don't like
to write documentation". It's part of their job. It shouldn't be my job (or
yours). If you were to learn to document this code, it would be a very
inefficient use of your time. You would spend more time learning the coding
language and trying to understand the code than you would writing the
documentation (for the code). If you want to be a programmer, fine, but
letting the programmers off the hook of what should be their responsibility
is not the way to go.

Good developers document as they go. They either learn to document better,
or they learn to code better so they don't have to explain as much in their
documentation. Programmers who don't document code would not be hired at
this company, nor many other companies. They would certainly not be
promoted. A programmer who can't (or won't) document code probably doesn't
write requirements, specifications or design documents either. No thanks.

Programmers not documenting code is a management issue. You need to ask
management why the programmers cannot document their own code. If you have
legacy code, and the programmers who wrote it are long gone, then you need
a programmer with expertise in that coding language to go through it and
document it. If you are interviewing "applicants who want to do end-user
documentation" these are the wrong people for the job. Documenting code
does not require the same level of writing skill as does writing end-user
documentation. If you must, have a programmer at least comment all the
code, and then you can pretty it up and rewrite it if necessary. That would
be a much better expenditure of resources.

--Beth

Beth Agnew
Senior Technical Writer, InSystems Technologies Inc.
65 Allstate Parkway, Suite 100  Tel: (905) 513-1400 ext. 280
Markham, Ontario, Canada L3R 9X1        Fax: (905) 513-1419
mailto:bagnew -at- insystems -dot- com    Visit us at: http://www.insystems.com