db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bryan Pendleton <bpendleton.de...@gmail.com>
Subject Re: Documentation and DITA: The Derby Experience?
Date Wed, 18 Aug 2010 14:08:59 GMT
> I've been recommended to look into DITA and can see that Derby uses it
> for its documentation.

As an ordinary Java developer (that is, I'm not a full-time tech writer), I've
found that I can successfully build and maintain the Derby documentation. I
don't have to use many special tools; for the most part the tools are the
same as those I use for my ordinary development (Vim, Ant, svn diff, etc.)
All the tools that I use are freely available.

However, we are blessed on the Derby project to have several professional
tech writers who are regular committers, and I think that when the initial
Derby documentation was set up, there was a pretty substantial effort to
construct the initial docs implementation. So I am benefitting from those
situations, which perhaps are special to Derby.

DITA seems quite powerful, and yet the actual documentation that you write
and maintain is just some simple marked-up XML files. Feel free to browse
the Derby docs source tree to get a feel for what the typical DITA source
file looks like in Derby. For example, here's a random, yet quite typical, file:
http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefmonthfunc.dita?view=markup

I'd pretty much have to call our docs setup a complete success, with the
caution that I mentioned above that I suspect the initial setup was rather involved.

Hope this helps!

bryan

Mime
View raw message