On Fri, 2009-05-22 at 11:10 -0700, stan wrote: > Speaking as an (ex?) programmer, writing the code is fun, writing the > documentation is pure drudgery. And really, the > only person who can realistically write documentation is the > programmer. They know all the ins and outs of the code, > and the functionality they programmed in. It can be done through an > intermediary, someone who questions the programmers > and finds out the functionality and then writes it in comprehensible > language, but the chance that someone unfamiliar > with the code is going to write decent documentation is pretty slim. > > Of course, in the days when code was written to specs, the specs were > the kernel of the documentation and only needed to > be modified with changes. I don't think there are such things as > specs in the open source world, just some general > vision statement of what the software should accomplish, usually about > as detailed as the description from the RPM. :-) My view is that if the programmer can't write a lucid description of what his stuff does, it means he doesn't really understand it himself. This doesn't mean writing a three-line comment for every internal function, it means having a coherent conception of what your program is for and how it works, and being able to explain at least the former at a level appropriate to the target user. There's a strong correlation between good code and good docs. The idea that writing the docs is drudge-work best left to an intern does profund damage to the image of programming as a serious activity. poc -- fedora-test-list mailing list fedora-test-list@xxxxxxxxxx To unsubscribe: https://www.redhat.com/mailman/listinfo/fedora-test-list
