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
