Re^2: What sets Perl back

in reply to Re: What sets Perl back
in thread What sets Perl back

Most good programmers write some really crappy documentation. And even if they do go to the trouble of writing documentation, there's the chance that it's not kept in sync with the actual code.

I would love to see 'Writing Documentation 101' taught as part of a computer science degree, but even if the programmer could manage to write something, it goes against just about everything most programmers hold valuable -- saving time.

We write tools to save ourselves time ... often, it's write once, and forget about it. Until you start getting into something that's cyclic in nature, with a rather long period (eg, you only have to do it once a year or so), you think to yourself that there's no point it documenting things. Come the third or fouth time of trying to remember what you were doing, you start to appreciate how important the documentation is ... but even then, you're writing documentation for yourself, and not for others.

Have you ever had a class, where the teacher wrote the book? If the teacher makes no sense in class, you read the book, and realize that it's all been presented in the same way that makes no sense to you. The only benefit of writing documentation is in forcing the programmer to think about things in a way to present it clearly.

Personally, I've been writing my interfaces before I write the programs lately -- you can write the general user documentation, make sure it plugs in with other programs that might make use of it, and then fill in the blanks. But I've gotten stung a few times by minor changes that I forgot to express in the docs, and when I look at it 6 months later, I have to remember why I made changes that broke the docs (I know, anything in the docs should be expressed as a test, so that the errors will show up when I run the text suite, and I need to set up the test suites to generate reports nightly, in case something gets committed by someone else to the repository)

Right ... so as I've gone off on a tangent -- what's the right solution? Hopefully, get someone else to write the docs, or to ask you enough questions early on, that you start answering them, and recording them as documentation. Writing the docs yourself does no good unless you then get someone to use the docs, and essentially test them to make sure that they don't confuse people.

Comment on Re^2: What sets Perl back

Replies are listed 'Best First'.
Re^3: What sets Perl back by JohnMG (Beadle) on Dec 12, 2005 at 07:35 UTC
Most good programmers write some really crappy documentation. [snip] but even if the programmer could manage to write something, it goes against just about everything most programmers hold valuable -- saving time. It's, of course, actually a time saver in the long run to write good docs. Good docs make it easier for others (co-workers? folks on the qa team? do-gooders in the free software community?) to work on your code rather than you having to do it yourself, Good docs save you time when you need to re-familiarize yourself with your own code that you may not've touched in a while Personally, the first thing I look for in a free software project is good docs. If the docs are good, you can always write tests and fix or update the code as-needed. If the code is ok, but the docs aren't good, the software is (in the long run) only useful to those who are willing to pore over it and try to figure out what it's supposed to be doing.	[reply]
Re^4: What sets Perl back by jhourcle (Prior) on Dec 12, 2005 at 13:55 UTC
Yes, I know good docs time saver, but most programmers I know don't write good docs -- they might be a fantastic programmer, but they couldn't write down a complete thought to save their lives -- for them, writing documentation is like trying to write a report in high school -- a whole lot of work for relatively little payback (why do the extra effort for a '100' grade, when a '90' grade shows up the same on a report card? And hell, if the '70' is 1/2 the effort, it's still a passing grade) There are those folks who can bridge the two fields, and there lots of 'big names' out there, who both program and write books professionally, but there are a whole lot more who are the folks in the trenches, writing code day in and day out. If you have an asshole manager bitching that you're behind schedule (mostly because they kept assigning you to other 'emergencies' that kept popping up, and they set the damned schedule before they even asked you what it was going to take to complete), documentation gets dropped. I have a long running joke from one of my past jobs, where I have specifically listed in my notebook that documentation was listed as 'phase two' (we never got to phase two -- the job got implemented, and I moved on to other projects) In many places where good programmers cost money, it's not cost effective in the eyes of idiot management to have the lead programmers write documentation. Luckily, I don't work for those types of places anymore, and I get to write documentation in a mostly timely manner, but when I'm buckling under, trying to prep for a release (typically dictated by the timing of AAS and AGU meetings), I'll focus on the code, and the documentation might get behind.	[reply]

In Section Meditations