On Sun, 9 Jan 2000, Don Baccus wrote:
> At 05:27 PM 1/8/00 -0500, Tom Lane wrote:
>
> >I also object strongly to the lack of documentation. Patches that
> >change public APIs and come without doco updates should be rejected
> >out of hand, IMNSHO. Keeping the documentation up to date should
> >not be considered optional --- especially not when you're talking
> >about something that makes subtle and pervasive changes to library
> >behavior.
>
> Boy, Tom's really laid it out in excellent style. If the author of
> such changes doesn't document them, chances are that the documentation
> won't get done. That's very bad.
>
> The automatic rejection of undocumented patches that change the API
> or other user-visible behavior shouldn't be controversial. I know
> there are some folks who aren't native-english speakers, so perhaps
> you don't want to require that the implementor of such patches provide
> the final documentation wording. But the information should be there
> and spelled out in a form that can be very easily moved to the docs.
These patches were originally submited before Xmas by Alfred, asking for
feedback on them and possibly pointing out errors in implementation...he
wanted to get a feel whether or not it was *worth* him putting further
work into them. They fell on silent ears.
Personally, I wouldn't waste my time on documenting something that, in the
end, I'd be the only one using...I'd get feedback on the usefulness first,
and then deal with building up the documentation after I've found out that
its worth it...
Alfred didn't ask "do I need to add documentation?" ... he knew that ...
he asked whether or not the implementation was appropriate, and was worth
his time to continue working ...
Marc G. Fournier ICQ#7615664 IRC Nick: Scrappy
Systems Administrator @ hub.org
primary: scrappy@hub.org secondary: scrappy@{freebsd|postgresql}.org