db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Rick Hillegas <rick.hille...@oracle.com>
Subject Re: Documentation and DITA: The Derby Experience?
Date Wed, 18 Aug 2010 13:03:15 GMT
Hi Alex,

I believe that we use DITA because it lets us produce both HTML and PDF 
manuals from the same source XML. The conversion of Cloudscape docs to 
DITA happened more than 5 years ago. Since then, better free tools might 
have come along.

My major dissatisfaction with DITA is that we can't produce an index 
from our manuals. This was a very useful feature of the Cloudscape 
manuals. Some day I would like to migrate away from DITA so that we can 
exploit our index markup again.

My other dissatisfaction with DITA is the blizzard of warnings which it 
produces when we generate our full doc set. I cannot see signal in this 
noise, and I wonder whether we are overlooking mistakes that are 
gradually accumulating in our source XML.

I'm sure that Kim can give you more information. Some more comments 
inline...

Hope this helps,
-Rick

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?
>   
It does produce both HTML and PDF output.
> What are the problems you've found?
>   
Please see above.
> Are you able to do it with just free tools?
>   
Yes.
> Is it overkill for a "small" OSS project? or is the extra hassle worth it?
>   
I don't know how much of a hassle the original conversion was. Using it 
for incremental changes does not seem difficult to me. My chief 
complaint here probably applies to other free formats: the lack of good, 
open source wysiwyg XML editors.
> 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
>
>   


Mime
View raw message