Discussion: Feedback needed on the Documentation Review process

[Laura Stewart <sc...@gmail.com>]

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?

Did you understand how to log your comments?

There were only a few people that participated in the review.  What
prevented more people from participating?

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?

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

Thanks!
-- 
Laura Stewart

Re: Discussion: Feedback needed on the Documentation Review process

[Daniel John Debrunner <dj...@apache.org>]

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

[snip]

> Was the wiki a good way to conduct the reviews?

I found adding an entry to the wiki was in some ways more painful than 
entering a Jira issue. The pain was the manual formating of the table 
and distractions would cause one to lose the edit lock on the wiki page, 
in one case losing my comments.

Then with the wiki there is no good tracking of how the issue was 
resolved, no link to the patch number or the Jira entry that fixed it.

So maybe just using Jira is better as it's fairly quick, doesn't lose 
issues and allows tracking. Might result in a large number of Jira 
issues but I'm nt sure that's really a problem.

Some direct markup of an html page on the site directly would be much 
better though. :-) I saw a page with a number of minor mistakes on it 
the other day, but it seemed a lot of effort to write those up in a Jira 
entry, namely having to describe the mistake, which document, section, 
paragraph etc. that it occurs in.

Dan.

Re: Discussion: Feedback needed on the Documentation Review process

[Yip Ng <yi...@gmail.com>]

On 11/3/06, Laura Stewart <sc...@gmail.com> wrote:
>
>
> Does anyone else have comments that you want to share on the
> Documentation Review process?



In my opinion, I think the documentation review should be done using jira.
Most code reviews are done in jira and I found it to be quite effective.


Regards,
Yip Ng

Re: Discussion: Feedback needed on the Documentation Review process

[Laura Stewart <sc...@gmail.com>]

On 10/17/06, Laura Stewart <sc...@gmail.com> wrote:
> On 10/17/06, Rajesh Kartha <ka...@gmail.com> wrote:
> > Comments inline.
> >
> > Regards,
> > -Rajesh
> >
>
> > > 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.
>
> Having a single issue per manual worked okay for me to submit patches,
> but I think that it would be harder to track individual comments and
> their status.
> Is there a way to create a sub issue or linked issue for individual comments?
>
> --
> Laura Stewart
>

Does anyone else have comments that you want to share on the
Documentation Review process?

-- 
Laura Stewart

Re: Discussion: Feedback needed on the Documentation Review process

[Laura Stewart <sc...@gmail.com>]

On 10/17/06, Rajesh Kartha <ka...@gmail.com> wrote:
> Comments inline.
>
> Regards,
> -Rajesh
>

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

Having a single issue per manual worked okay for me to submit patches,
but I think that it would be harder to track individual comments and
their status.
Is there a way to create a sub issue or linked issue for individual comments?

-- 
Laura Stewart

Re: Discussion: Feedback needed on the Documentation Review process

[Rajesh Kartha <ka...@gmail.com>]

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!