Re: Documentation Status and Reviews

[Shaun McCance <shaun mccance medsphere com>]

On Tue, 2005-01-25 at 10:27 +0000, Stuart Ellis wrote:
> 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.

Well, shouldn't they be?  ;)

Worst case scenario if the process isn't completed is that the document
is no worse off than it would have been otherwise.  Realistically, I
don't think we'll get full buy-in on this release cycle.  But it's a
start.

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

Sure.  I think we'd have to allow some fudge factor.  If a writer only
manages to muster up one peer review, but is pretty confident in the
document, he could mark it Candidate status.  And if he gets four or
five peer reviews, all the better.

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

Sure.  Again, we can let things slide.  Ultimately, everything is up to
the documentation maintainer.  I think technical reviews can be really
helpful, though.  And people should try to get them early in the review
process, if they can.

I have mentioned this to a few developers, and most of them seemed
willing to do technical reviews.

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

Well, a lot of writers often don't have the best DocBook skills.  There
are quite a few gotchas in DocBook, and a lot of our documents suffer
from them.  But certainly, markup review shouldn't be the primary task
for peer reviews.  If a reviewer wants to look for markup problems,
great.  But don't require it for peer reviews.

I do think, however, that final reviews should absolutely check markup.
The people doing final reviews should be those experience with Gnome
documentation and DocBook.  Markup problems are typically easy to fix
last-minute, so there's really no problem putting this off until the
final review.

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

Agreed.

--
Shaun