Overheard from a colleague...

[blufive]

"What we need is a detailed design document of our system"

I've been making noises about how we should be writing documentation for at least the last 15 months. This particular colleague always flys off the handle at the merest suggestion that he should document his code. He's responsible for a large part of the system (indeed, the entire component) he's now complaining about.

I suspect that if I nagged him about documentation, he'd flip, as usual. I despair, sometimes.

Cause. Effect. LEARN! Is it really that hard, just because cause and effect are six months apart? Apparently so, judging by the number of "professional" programmers who churn out code all day without bothering at any point to write down what it does...

Comments

but...

[blufive.livejournal.com]

What really drives me nuts is, we're working in Java. We have Javadoc, which is an excellent tool. Class comments are the perfect place to explain what each class does, how it works, what it interacts with, etc. The problem is more the mentality than the tools, unfortunately. "We don't need to document this, we're the only ones who will ever see it". AAAAARGH!

A follow up comment: "Gav, have you documented this module?" To which the reply was "No. You wrote it and you've never explained it to anyone. I don't have a clue how it works." Fortunately, I didn't have to add "you should have documented it yourself", cos someone beat me to it.

Re: but...

[yonmei.livejournal.com]

We have Javadoc, which is an excellent tool. Class comments are the perfect place to explain what each class does, how it works, what it interacts with, etc. The problem is more the mentality than the tools, unfortunately. "We don't need to document this, we're the only ones who will ever see it"

At my last job, one of my tasks as the company's only technical writer was to clean up and make comprehensible the stuff that the developers had typed into the Javadoc. This was because although they had often entered information, since they were required to do so, it was almost invariably in one of three states (or sometimes a combination):

Original material, verbose, mispelt, incoherent, and requiring major editing.

Original material, written in very generalised form so that it can be recycled for (3)

Material cut-and-pasted from (2) - and, occasionally, from (1) - to fulfil the requirement of having something in the Javadoc.

Listed in order of preference...

Sod!

[yonmei.livejournal.com]

The "ol" tag doesn't work in LJ!