On Wed, 27 Jan 2010 21:41:02 +0800
Craig Ringer <craig@postnewspapers.com.au> wrote:
> I don't code on PostgreSQL's guts, so I'm perhaps not in the best
> position to speak, but:
>
> - Documentation has a cost too, particularly a maintenance cost.
> Outdated docs become misleading or downright false and can be much
> more harm than good. So a reasonable balance must be struck. I'm
> not saying PostgreSQL is _at_ that reasonable balance re its
> internal documentation, but there is such a thing as
> over-documenting. Writing a small book on each function means you
> have to maintain that, and that gets painful if code is undergoing
> any sort of major change.
I'd be willing to pay for a book.
> - It's easy to say "should" when you're not the one writing it.
> Personally, I try to say "hey, it's cool that I have access to
> this system" and "isn't it great I even have the right to modify
> it to do what I want, even though the learning curve _can_ be
> pretty steep".
Well... I tend to generally make available to others everything I
learn. I'd be nice a more advanced use of doxygen so it would be
easier to have a map of functions.
> Hey, you could contribute yourself - patch some documentation into
> those functions where you find that reading the source isn't clear
> enough, and they really need a "see also" or "called from" comment
> or the like.
Right now I've not enough knowledge to hope my notes get into the
source code. Once I've a working piece of code I'll put the
information I gathered in the process on my web site and if someone
find them worth for a better place I'll release them with a suitable
license.
--
Ivan Sergio Borgonovo
http://www.webthatworks.it
