Feedback requested on proposed change to documentation format

[Kim Haase <Ca...@Sun.COM>]

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.

Conversion of the documentation source to DocBook would be a one-time 
task that I'd be willing to take on. I can also use an existing DocBook 
build system that, like the DITA toolkit, uses only freely available 
open-source tools. The only change is that it would need to convert from 
Gnu make to Ant to be compatible with the Apache license. The goal would 
be to make it no more difficult to build the documentation than it is 
today (and ideally easier). I would hope to complete the project for the 
next release of Derby (10.5).

Before I explore these possibilities further, I'd like feedback from the 
community. It seems that few people are currently working on the Derby 
documentation, but many of you are using it. I would be grateful for 
your thoughts.

Kim Haase

Re: Feedback requested on proposed change to documentation format

[Kim Haase <Ca...@Sun.COM>]

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 --

Kim

Re: Feedback requested on proposed change to documentation format

[Daniel John Debrunner <dj...@apache.org>]

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.

Re: Feedback requested on proposed change to documentation format

[Rick Hillegas <Ri...@Sun.COM>]

Hi Kim,

+1 to a documentation format which lets us build indexes and 
intra-document hotlinks. If we migrate to a new system, I hope that it 
preserves the following features of the old system:

1) Is driven by an ant script. This would make it easy to integrate into 
a master target which the release manager could use to build 
documentation and code.

2) Only uses tools which come with Apache-compatible licenses.

3) Only uses tools which are easy to get off the web without a lot of 
prep and license click-through.

Thanks,
-Rick

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.
>
> Conversion of the documentation source to DocBook would be a one-time 
> task that I'd be willing to take on. I can also use an existing 
> DocBook build system that, like the DITA toolkit, uses only freely 
> available open-source tools. The only change is that it would need to 
> convert from Gnu make to Ant to be compatible with the Apache license. 
> The goal would be to make it no more difficult to build the 
> documentation than it is today (and ideally easier). I would hope to 
> complete the project for the next release of Derby (10.5).
>
> Before I explore these possibilities further, I'd like feedback from 
> the community. It seems that few people are currently working on the 
> Derby documentation, but many of you are using it. I would be grateful 
> for your thoughts.
>
> Kim Haase