db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kim Haase <Camilla.Ha...@Sun.COM>
Subject Re: Feedback requested on proposed change to documentation format
Date Mon, 06 Oct 2008 16:57:44 GMT
On 10/06/08 11:07, Daniel John Debrunner wrote:
> Kim Haase wrote:
>> I'd like to know what the Derby community thinks about the possibility 
>> of changing the source format of the Derby documentation from DITA to 
>> DocBook and using a different build system. DocBook is a schema that 
>> can use an XML DTD, like that of DITA; see http://www.docbook.org/ for 
>> more information.
>> Our DITA toolkit has some problems that the Derby community hasn't 
>> been able to solve with our current level of resources:
>> - It does not allow us to create book indexes or to create live links 
>> between manuals. The feedback we've received is that this makes the 
>> documentation hard to use.
>> - Links to tables usually don't work in the PDF or HTML Book versions.
>> - Building the PDF and HTML Book versions of the docs causes errors 
>> and warnings that we can't seem to get rid of.
> That says what DITA cannot do, but doesn't indicate any benefits of 
> docbook, what would be the benefits of switching?
> Dan.

The chief benefit is that it would resolve these problems without losing 
the advantages of the topic-oriented structure of DITA or the ability of 
the toolkit to generate documentation in various formats.

DocBook, though highly structured, is also somewhat less restrictive: it 
does not force you into a small subset of allowed elements within 
topics, which in the Derby docs has let to some odd choices of elements.

I'm still in the early stages of investigating this change, and if the 
disadvantages turn out to outweigh the advantages I'll be the first to 
say so.

Hope this helps --


View raw message