Documentation Status and Reviews

[Shaun McCance <shaunm gnome org>]

During the last release cycle, we worked on a number of the documents
collaboratively.  We got quite a few new writers involved, and that was
really nice.  But there was often confusion as to the status of all the
documentation, and this hurt our efforts to have community-build docs.

I'm proposing we track the status and reviews of each document with a
simple process.  We can use the live.gnome.org wiki to keep track of
everything.

http://live.gnome.org/DocumentationProject/DocTable2.10

Basically, each document will go through four states: Incomplete, Draft,
Candidate, and Final.  The maintainers of each document (or in the case
of community-built documentation, seasoned GDP members) will be asked to
get various reviews, and to mark their document's status appropriately.

What I'd like to see is each document getting one technical review, at
least three peer reviews, and one final review.

A document starts its lifecycle as Incomplete (unless it doesn't exist,
or is only a stub, in which case it's Missing).  Maintainers should then
update the documentation to reflect changes to the documented program in
the current release cycle.  When the maintainer feels the document has
basically all the information it needs, she should try to get the first
four reviews.

Technical reviews should come from the application maintainer or other
developer with a good familiarty with the application.  These should be
checking for technical accuracy.  Make sure everything is correct, and
that nothing important has been overlooked.  This would also be a good
time to point out "gotchas", quirks that users might run into and not
understand.

The three peer reviews should check the document structure to make sure
it's laid out well and that information is easy to find.  They should
also check grammar and style, and if possible, look for problems in the
DocBook markup.

When the document maintainer has dealt with these reviews, the document
should be marked Candidate.  This means the maintainer feels that the
document is ready, and wants a final go-ahead.

When a document is a Candidate, a seasoned GDP member should do a final
review.  At this point, we shouldn't aim to do massive restructuring to
the document.  It's too late for that.  But simple grammer and stylistic
problems should be identified.  Additionally, the final reviewer should
check for markup issues, and make sure that the OMF file is correct.

When the maintainer has dealt with any issues in the final review, he
can mark the document Final, notify the translation team, and go have a
well-earned drink.

Caveat: When I say "dealt with a review", I do not mean the maintainer
needs to take every suggestion from the review.  The maintainer is the
final say.  Reviewers shouldn't commit changes to CVS, unless they've
been given permission from the maintainer.  A maintainer is perfectly
free to reject all the suggestions in a review.  But she should look at
them.

Note: In order to encourage community involvement, we would like all the
reviews somewhere permanent and publicly-viewable.  Sending them to this
(or another) mailing list is fine, as is posting them to bugzilla.  When
a review is posted, a link to it should be added to the doctable.


So that's my proposal.  I'd like to get everybody on board with this, so
that we can get new writers working quickly and efficiently.  It really
is a shame when we have an eager potential contributor, and we just let
him slide by because we don't know what he should do.

Questions, comments, ideas, flames?

--
Shaun