Re: Demanding API documentation

[Brian Cameron <Brian Cameron Sun COM>]

Murray:

>> (2) which the current platform
>> totally fails at, indicating that there isn't much consensus or
>> support for it.
>  
> I disagree. I proposed formalising this because I think we are ready for it.

The GNOME platform has demonstrated a good degree of interface stability, and
the documentation for platform libraries is, for the most part, in reasonable
shape.  There are a few issues that should be treated as bugs.  There are
probably a few Platform libraries that shouldn't be used by ISV's (such as
ORBit2 and libbonobo), but aside from clarifying such details the platform
is already Stable.

The goal is not to create draconian rules that module maintainers are
forced to follow, but to instead create a communication mechanism so that
the GNOME desktop can more clearly describe which interfaces are
intended for ISV use.  Today, it simply isn't clear.  The main problem
is simply that the current process used to ensure interface stabiltiy and
quality isn't documented.

Making a policy recommending that Platform interfaces that are intended for
ISV use should be well documented is a reasonable policy.  Does this
mean there won't be issues.  No, but these can be treated like bugs just
like anything else.

I disagree with Mark that it is necessary for the entire Platform to
become Stable before trying to define "best practices" standards or
platform expectations.  Some libraries in the GNOME stack meet all
reasonable stability requirements and are well accepted by ISV's,
such as glib and GTK+.  Why not give such modules additional
recognition as being "ready for ISV use" and other modules will
naturally want to follow the same standards to achieve similar
recognition.  It might be reasonable to expect that future modules
that wish to enter the platform meet such a requirement, just to
set the bar in the right place from a "best practices" standpoint.

The advantage is that this creates a clear communication mechanism
so ISV's understand which interfaces to use.  Obviously, they should
be interfaces that the module maintainer believes should be ready
for ISV use and agrees to document following reasonable standards.

Brian