Re: [Fwd: Re: Demanding API documentation]

[Elijah Newren <newren gmail com>]

On 11/29/05, Federico Mena Quintero <federico ximian com> wrote:
> On Tue, 2005-11-29 at 10:41 -0700, Elijah Newren wrote:
> > Cool, thanks for doing this Federico.  I took a quick look and just
> > made a couple minor changes; it'd be great if others could also have a
> > look.
>
> Thanks for the changes; the page is clearer now.
>
> However, I see that you moved the "modules with no new APIs need to have
> more of their older APIs documented" part to Recommendations, instead of
> Requirements.
>
> The problem with that approach is exemplified in gnome-vfs, libbonobo*,
> and other infamous libraries.  Their APIs seldom get additions; they
> never get docs.  Eventually the maintainer goes away; and since he is
> the only person that knows the API, a few years pass and then we start
> saying, "we should deprecate this because nobody understands it".  I've
> seen this happen many times throughout the history of GNOME :)
>
> If a library is "done enough" that it doesn't need more APIs, that's the
> perfect time to sit down and document all that is missing.
>
> I'd like to move that bit back to Requirements :)

I think it'd make sense and I'd support it BUT it must be approved by
the community.  Follow up to Murray's email on d-d-l and see if
maintainers will also commit to this extra requirement.  If they do
(i.e. no one objects after enough time), feel free to send it back to
the requirements section.

Cheers,
Elijah