Re: Documentation Status and Reviews

["Stuart Ellis" <s ellis fastmail co uk>]

On Mon, 24 Jan 2005 23:27:44 -0600, "Shaun McCance" <shaunm gnome org>
said:
> 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

This looks good.
 
> 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.

A note of caution - the process you've described hinges on the listed
maintainers being able to remain fairly responsive throughout.  

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

I like the requirement for a peer review, but I think that it may be
difficult to get three peer reviews for each document, at least during
the first iteration of this process.  People tend not to comment unless
something is obviously broken.

> 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.

This requires buy-in from a number of developers, so it is probably
something that needs to be promoted formally.  I'd suggest tying
documentation reviews in with usability reviews in some way, since that
process has a wide degree of acceptance.

> 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.
> 

Reviewing DocBook markup is probably more technically demanding and
time-consuming than reviewing the content in a HTML build, so I'd
suggest giving the responsibility for it to the maintainer, who is
likely to have the necessary skills.

> 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.
> 

I'd suggest doing the reviews on the mailing list, and keeping Bugzilla
submissions to targetted issues and patches.  Reviews can become
discussions, which isn't necessarily a bad thing.  Mailing list threads
are also a lot more visible than Bugzilla bugs.
--

Stuart Ellis
s ellis fastmail co uk