User Documentation Requirements

[Shaun McCance <shaunm gnome org>]

In the 2.15 release cycle, we moved the new module proposal
period to the beginning of the release cycle, while leaving
the decision around the feature freeze.  This allowed users
to test the new modules, and allowed developers to make an
effort at integrating with them.

This was an incredibly good idea, and whoever thought of it
should get a big pat on the back.  It worked out well, and
we've brought it back or 2.17.

It's no secret that the documentation team is constantly
scrambling to make a dent in the documentation we need.
Part of this is a lack of tracking tools (on my very big
plate), but part of it is that we have a big pile of shit
dropped on us at feature freeze, and only two months to
dig through it.  It's insane.

I would like to propose requirements on maintainers of
user-oriented modules (that is, those modules that need
user documentation).  As a programmer and maintainer,
I don't think these introduce an undue burden.  And as
a documentation team member, I think they can help our
writers significantly.


Existing modules: At feature freeze, maintainers MUST
send the documentation team a list of things that have
changed that we care about.  Don't make us sift through
a ChangeLog or the NEWS file.  Tell us about any changes
to the interface, and explain any new features and how
users are expected to interact with them.  If there are
notable known bugs, let us know.

New modules: Between the time they are proposed and the
time we decide, new module maintainers MUST contact the
documentation team to try to get documentation in place.
Maintainers are expected to provide much of the same
information as existing module maintainers, except they
don't get to just give us the delta from six months ago.
Planned features for this release cycle should also be
provided.  After the decision (and thus feature freeze),
they should send us the same list of new stuff as the
rest of the maintainers.

New modules with existing documentation: Maintainers of
proposed modules that contain documentation MUST still
contact the documentation team, so that we know you're
there and can still review and work with your existing
documentation.

Bugzilla: All user-oriented modules MUST have a bugzilla
component for documentation issues.  The default assignee
MUST be an alias that we can watch, and it MUST NOT be an
alias that code-type stuff gets assigned to.  You may use
gnome-user-docs-maint gnome bugs, but it is not required.
If your bugzilla product is beanstalk, you could instead
use beanstalk-docs-maint gnome bugs   Do tell use when
you add or change such a component.

I am half-tempted to attempt to standardize the name of
this component, but I'd want to talk to bugmasters first
to see how easily we could transition.

Objections?

--
Shaun