Mailing-List: contact derby-dev-help@db.apache.org; run by ezmlm
Precedence: bulk
Reply-To: <derby-dev@db.apache.org>
Received-SPF: pass (athena.apache.org: local policy)
Message-ID: <4C6BF252.4000400@oracle.com>
Date: Wed, 18 Aug 2010 10:46:42 -0400
From: Kim Haase <camilla.haase@oracle.com>
Reply-To: camilla.haase@oracle.com
User-Agent: Thunderbird 2.0.0.23 (X11/20090910)
MIME-Version: 1.0
To: derby-dev@db.apache.org
Subject: Re: Documentation and DITA: The Derby Experience?
References: <AANLkTi=r6Zd3LFkDP+dFhrKd3x=WtLZE2VGQbWHx2+F4@mail.gmail.com>
In-Reply-To: <AANLkTi=r6Zd3LFkDP+dFhrKd3x=WtLZE2VGQbWHx2+F4@mail.gmail.com>
Content-Type: text/plain; charset=ISO-8859-1; format=flowed
Content-Transfer-Encoding: 7bit

Hi,

Rick and Bryan have done a great job summarizing the pros and cons of 
DITA for the Derby project.

As a tech writer I find DITA and our toolkit fairly easy to work with. 
Of course, I don't mind editing XML in a plain text editor -- some 
people might, since this process is a bit error-prone.

The initial tool setup to generate output from DITA involved some rather 
complicated work from a technical wizard, before I started on the 
project -- some of the original DITA toolkit XSL files were modified to 
generate the desired output. But the wizard is no longer working on the 
project and we haven't found a contributor with comparable expertise, so 
we are now pretty much unable to make fixes (like getting rid of all the 
warnings Rick mentioned). Nor have we been able to upgrade to a later 
version of the DITA toolkit. I would recommend starting with the most 
current toolkit for a new project -- it probably has capabilities we 
would take advantage of if we could (who knows, maybe we could generate 
indexes?).

I hope this is helpful. Feel free to ask more specific questions.

Kim Haase

On 08/18/10 04:56, Alex McLintock wrote:
> Hi,
> 
> I'm not a Derby developer - but am working on the documentation of
> another Apache project (Nutch). I'd like to know more about your
> documentation system.
> 
> I've been recommended to look into DITA and can see that Derby uses it
> for its documentation. In fact Derby seems to be the only Apache
> project which does (AFAICS).
> 
> Can you tell me how well it works for you?
> What are the problems you've found?
> Are you able to do it with just free tools?
> Is it overkill for a "small" OSS project? or is the extra hassle worth it?
> 
> If I were to set up DITA for a different Apache project should I copy
> Derby's structure (including using specific old jarfiles!) or start
> from scratch? I would prefer to copy Derby rather than roll my own,
> but that may mean I blindly copy your mistakes - if any.
> 
> Hopefully you wont think that discussing Derby's documentation is off
> topic for the dev list :-)
> 
> Thanks,
> 
> Alex
>