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

A possible solution?

[devilgate.livejournal.com]

Where I work we've found that we write vastly more internal documentation within our team since we started using a Wiki, specifically, TWiki.

If you haven't used one, it's a web-based collaboration tool. A bit different from a blogging system (it doesn't have the data-based approach, for one thing); more free-form.

It's simplicity itself, since you just type into a web form (much like the one I'm typing into now) with a few special codes that get converted into HTML. What else? It's free as in speech and beer, and as it's mainly just a Perl script, it'll run just about everywhere.

The key thing is to get people to use it, and somehow it caught on at our place. We've now got the best-documented forthcoming release I've ever known.

Getting the user documentation written, of course, will be another matter.