db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bryan Pendleton <bpendle...@amberpoint.com>
Subject Re: Discussion: What prevents you from updating derby documentation?
Date Wed, 25 Oct 2006 16:10:56 GMT
> I'd appreciate comments from any one else about updating docs...

I've been successful making a handful of documentation patches.

The changes I've made have been very small, confined to 2-3 pages
in the reference guide, and I've generally just been adding a
paragraph here and there. I simply mimic the existing text and
tags, and modify accordingly.

I've been able to setup and run the documentation build locally,
so that I can construct the HTML files and view them on my
machine to verify that they are acceptable.

I find writing in DITA format to be awkward and slow, so when I
have a lot of information I want to enter, I tend to prefer one of:
  - adding information to the Wiki
  - writing comments directly in the code
  - writing HTML or Text documents and attaching them to Jira issues

I haven't yet had a large docs project I wanted to do so I don't
know what I would do when I reached that point.

But for small concrete doc changes I intend to continue making
patches myself and committing them.

As far as concrete comments, here are the only couple things that
I had trouble with:
1) At one point I was using Ant 1.6.4 and the doc build had a problem
    with that version of Ant. I upgraded to 1.6.5 and it was fixed.
2) I find the file names in the DITA source to be rather haphazard.
    I understand there was an original mass-conversion which
    generated the strange numeric file names, so hopefully as we add
    new file names they will over time be better named.
3) I've hit some hiccups with the process which automatically
    publishes the docs onto the db.apache.org site following a
    commit. It's sort of a mysterious process and I think I just had
    a spot of bad luck.

Hope this was useful.



View raw message