On Thursday 11 December 2003 04:58 pm, s. keeling wrote: > Incoming from Richard Kimber: > > Aren't you missing the point that you need to understand it before you can > > document it, and that in many cases understanding does not come without > > documentation. > > If you need to understand it to use it, you've got the source. What > more could you need? That's not good enough? Don't use it. You > think it would be better with good documentation? Great. Go write > some. Oh, you want me to write some? Why? I don't think it needs > it since I have no trouble using it.
This defensive attitude is common, but not universal amongst developers. I actually like writing documentation for stuff I write. It often starts before the code does (but that usually means it needs to be revised a lot). Saying that the source code *is* the documentation is not unlike saying the Human Genome is an Anatomy & Physiology textbook. :-P I feel that good documentation (not to mention accurate spelling and grammar, etc) is an important craftsmanship issue, and I don't like to short-change it. I don't know how many times I've gone through my code just to fix the bad spelling in comment lines. The most embarrassing thing was when I had to change the API to my Zope product because I misspelled a word in a function name! That was really dumb. > The LDP is always looking for volunteers. Hint, hint. The common > sense answer to this whole thread is, "Don't look a gift horse in the > mouth." At one level, you're right -- no one has a right to force you to write documentation if you don't want to. Nor to space and indent your code so other programmers can read it. Nor to use variable names that are remotely related to the things they represent. That doesn't make obfuscation a good practice. And it's good practice that's being discussed here -- which is entirely appropriate for discussion, IMHO. I for one, like to keep improving at what I do. The service-bureau management model is highly flawed for many applications. Given a complete failure of the embedded approach, we turn to it as a last resort. Don't confuse that with success. That's like saying that having a fire department justifies sub-standard wiring. The people who know a program best are the ones who work on its internals. No one else can write documentation like the guy who built the thing in the first place. Failing that, you can have someone step in and write it, yes. But it'll never be as accurate as you'd like, nor as up-to-date. The ideal, for me, is to include documentation within the program in a literate-programming style, and generate the documentation from the code. This solves the other bad problem with Free Software documentation -- being WRONG. Wrong documentation can be worse than none! (With specific reference to Zope and Python code, this seems to be the biggest problem from my POV). IMHO, good documentation means more people using, testing, and (perhaps ultimately) contributing to my project. For those of us for whom those are principle motivators for releasing the code under a free-license in the first place, that's more than enough reason to make documentation part of the task. I also like to write documentation because I have a crummy memory. I write documentation so *I* can use it, too. :-) In fact I just spent all day yesterday reading one of my own manuals. OTOH, when I first released the program, I thought it was so simple that it didn't need documentation. But some of the people on the mailing list I announced to suggested that it really did. In retrospect, I can certainly see that they were right. I like Python for that, because there's so many great introspection tools built into it (I was never able to get anywhere with the original cweb literate programming system). Of course, I come from an academic background, so writing has always been part of my job. Anyway, I just wanted to point out that we're not all such curmudgeons about writing. :-D To the O.P. though -- bear in mind when you make this kind of criticism that you are criticizing somebody's baby. They do tend to get quite defensive. It takes a lot of confidence in yourself to accept criticism of your work without feeling personally attacked. ;-) One thing you get with free-licensed open source software that you don't get with the proprietary beast *is* actual contact with the author. That's unheard of for proprietary stuff! Cheers, Terry -- Terry Hancock ( hancock at anansispaceworks.com ) Anansi Spaceworks http://www.anansispaceworks.com -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]