Comments inline.
Regards,
-Rajesh
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
easier.
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
contributors.
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!
