Re: new apps without docs: policy request

[Shaun McCance <shaunm gnome org>]

On Thu, 2006-08-10 at 13:40 +0100, Joachim Noreiko wrote:
> For this release cycle, a few new apps and utilies
> have been added, and it seems none of them have any
> sort of documentation.
> This puts a bit of pressure on the documentation team,
> which is still running on a skeleton crew. There are
> still many applications with outdated docs (eg gedit),
> as well as new features to be documented.
> 
> I can see the rationale might be that if an
> application's developer asked the GDP to write a
> manual earlier in the cycle, the GDP might consider it
> a waste of time to write a manual for an untried
> application that might not be in the GNOME release.
> On the other hand, I'd rather waste time early in the
> cycle when there's very little documentation work to
> do, than have an extra heap of work in the final month
> when things get stressful. And even if an application
> isn't added to the official GNOME release, it's still
> used by distros and available at large: so it's not
> work wasted.
> Also, some of the apps this cycle are hardly new and
> untried: AlaCarte for example is already in Ubuntu
> Dapper.
> 
> I also think that just as the release team wouldn't
> consider an app or utility that was buggy, or
> incomplete, or had poor HIG compliance, so it should
> also consider a user manual to be a key feature of an
> application.
> 
> How do the other members of the GDP feel about this?
> Shaun, is this something we can pass on to the release
> team for next cycle?

We have a standing policy that new modules are *not*
required to have documentation in order to be accepted.
This policy dates back to, well, before my time.  The
case of documentation is different from complying with
the HIG in that HIG-compliance is something developers
can do on their own.

It's sort of like internationalization.  We do expect
developers to have internationalized their modules, but
we certainly do not expect them to have localized them
into every language Gnome supports.

This release cycle, we tried something a bit different
with respect to new module proposals.  We used to do the
proposals a week or so before the decisions, which would
coincide with the feature freeze.  This cycle, we tried
doing the proposals very early, but leaving the decisions
where they are.

I think this went nicely, and I expect the release team
will continue doing this.  In light of this new process,
I've been thinking over the last week of proposing a new
rule.  New modules proposals are not required to have
documentation, but in the months between proposal and
decision, maintainers must make a concerted effort to
work with members of the GDP to make docs happen.

Do bear in mind that, until feature freeze, any module,
new or not, can change completely behind our backs.  So
we shouldn't expect to be able to produce complete and
final documentation for new modules before the decision,
because the decision happens at feature freeze.  But we
can get a big chunk of the work done, or at least know
what we're getting ourselves into.

If the team likes this idea, I'll take it to the release
folks.  Team?

--
Shaun