Proposal - Doc Process Improvements

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

Hi

I've been working on updates to the Derby docs for a few months, and
now that we are close to completing this release I think that this is
a good time to revisit the processes (and stumbling blocks) that the
Derby project has for updating and reviewing the Derby documentation.

Here is what I propose:

1) Ask for feedback from the derby-dev community about the information
on the Derby Documentation page that describes how to setup your
environment, update the files, and submit patches.
http://db.apache.org/derby/manuals/dita.html

I can tell you from my own experience on updating Derby doc files,
that I would like to see more explicit instructions on how to locate
and update the DITA files, guidelines for tagging the files, and
formatting conventions.  I also think that it would be good to have an
FAQ for documentation update questions.

RECOMMENDATION: Start a derby-dev thread about the instructions and
guidelines for updating the Derby documentation files.
I volunteer to start this thread and implement the recommendations
from the community.


2) Ask for feedback from the derby-dev community about the
documentation review process.
http://wiki.apache.org/db-derby/TenTwoDocReview

A wiki was used to capture documentation review comments. Was the wiki
a useful tool for the reviews? Were the instructions for contributing
to the documentation reviews clear? Are there other ways to review the
documentation that would be better?

RECOMMENDATION: Start a derby-dev thread about the documentation review process.
I'll volunteer to drive this discussion unless somebody else would
like to -- just let me know if you do :-)

-- 
Laura Stewart

Re: Proposal - Doc Process Improvements

["Jean T. Anderson" <jt...@bristowhill.com>]

Your proposal sounds great to me, Laura.  I added more comments below.

Laura Stewart wrote:
...
> Here is what I propose:
> 
> 1) Ask for feedback from the derby-dev community about the information
> on the Derby Documentation page that describes how to setup your
> environment, update the files, and submit patches.
> http://db.apache.org/derby/manuals/dita.html
...
> RECOMMENDATION: Start a derby-dev thread about the instructions and
> guidelines for updating the Derby documentation files.
> I volunteer to start this thread and implement the recommendations
> from the community.

Your recommendation sounds good.

The http://db.apache.org/derby/manuals/dita.html link you mention is
part of the forrest-generated web site. The source for that particular
file is at
https://svn.apache.org/repos/asf/db/derby/site/trunk/src/documentation/content/xdocs/manuals/dita.xml
.

Information on how to checkout and build the web site is at
http://db.apache.org/derby/papers/derby_web.html . Web site instructions
also need more and better information. For example, they need to explain
that the files under http://db.apache.org/derby/docs are actually
generated separately from the web site and the web site simply points to
those files hopefully achieving an integrated experience for the end user.

> 2) Ask for feedback from the derby-dev community about the
> documentation review process.
> http://wiki.apache.org/db-derby/TenTwoDocReview
...
> RECOMMENDATION: Start a derby-dev thread about the documentation review
> process.
> I'll volunteer to drive this discussion unless somebody else would
> like to -- just let me know if you do :-)

Again, your recommendation sounds good.

Thanks for all your efforts on the docs.

 -jean