Re: Proposing Tracker for inclusion into GNOME 2.18

[Shaun McCance <shaunm gnome org>]

On Thu, 2006-10-19 at 18:29 -0400, Joe Shaw wrote:
> Hi,
> 
> On Thu, 2006-10-19 at 23:31 +0100, Don Scorgie wrote:
> > (Not getting into the *cough* discussion *cough*, just wanted to add 1
> > comment)
> 
> :)
> 
> > On Thu, 2006-10-19 at 18:11 -0400, Joe Shaw wrote:
> > > 
> > > (As an aside, I thought there was consensus that all new modules had to
> > > be fully documented for acceptance?)
> > 
> > There was never really a consensus.  There was a "We'd really like it if
> > there was at least some documentation.  And a developer to answer our
> > questions while we write for you.  Pretty please?" from the doc team.
> > Unfortunately, that particular thread (IIRC) died quickly.
> 
> I was thinking more along the lines of new APIs in GNOME (not sure if it
> was platform or desktop).  In any case, thanks for the clarification.

Right, one has to distinguish between user documentation and
developer documentation.  And with developer documentation,
one has to distinguish between reference documentation and
more expository sorts of documentation.

If I recall correctly, there was a general consensus that
all new APIs in the developer platform must have reference
documentation.  And just as with pretty much all platform
requirements, APIs in the desktop are strongly advised to
pretend they're in the platform.

All that said, I do have something to say about expectations
on user documentation.  But I'll do the right thing and start
a new thread for it.

--
Shaun