db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rajesh Kartha <karth...@gmail.com>
Subject Re: Discussion: Feedback needed on the Documentation Review process
Date Tue, 17 Oct 2006 17:26:10 GMT
Comments inline.


Laura Stewart wrote:

> For the 10.2 Documentation Review process, a wiki was used to log
> comments and track the status of those comments.
> http://wiki.apache.org/db-derby/TenTwoDocReview
> The purpose of the review is to take a comprehensive look at the
> documentation.  Because most documentation updates are made for an
> isolated bug or feature, the new content isn't always looked at from a
> broader, library perspective. The end of cycle documentation review
> enables the community to take a look at the documentation as a whole.
> As someone who implemented a large number of the comments, I am
> interested in hearing feedback on the process:
> What worked well and what needs to be improved in the documentation
> review process?
> Was the wiki a good way to conduct the reviews?
Maybe it is the MoinMoin - Derby wiki that does not allow an easier way 
to edit tables, but I found
adding/editing the pages not that friendly. Updating a JIRA issue seemed 
So if we have to continue using the current wiki, maybe a JIRA issue for 
each manual could be easier, where
reviewers can add the comments to. This issue can be closed if the 
majority of the comments are addressed and
a new JIRA issue can be created, if needed, for any unaddressed ones.

> Did you understand how to log your comments?
Thru discussions on  the list  it was made clear in the begining, so I 
did not have any issues.

> There were only a few people that participated in the review.  What
> prevented more people from participating?
I agree, would be interesting to find out.
Anyways, I think at a minimum we can ensure that the doc review cannot 
be marked complete
unless, for all the new features, we have sign-off from the respective 

> Is the end of cycle the best time to perform the comprehensive review?
> Should the comprehensive review be performed at the beginning of a
> feature cycle?  In the middle of a feature cycle?
I  think, to incorporate the  newer feature docs, end of the cycle 
review seems to work.
But if a start/mid cycle comprehensive review (without the new features) 
is initated, we
will have to do another round -  for the new features only. This can 
definitely help for
some doc refinement/clean-up and may be workable if we all in the community
decide to participate.

> Please provide your feedback so that the documentation review process
> can be improved.
> Thanks!

View raw message