Hi,
Rick and Bryan have done a great job summarizing the pros and cons of
DITA for the Derby project.
As a tech writer I find DITA and our toolkit fairly easy to work with.
Of course, I don't mind editing XML in a plain text editor -- some
people might, since this process is a bit error-prone.
The initial tool setup to generate output from DITA involved some rather
complicated work from a technical wizard, before I started on the
project -- some of the original DITA toolkit XSL files were modified to
generate the desired output. But the wizard is no longer working on the
project and we haven't found a contributor with comparable expertise, so
we are now pretty much unable to make fixes (like getting rid of all the
warnings Rick mentioned). Nor have we been able to upgrade to a later
version of the DITA toolkit. I would recommend starting with the most
current toolkit for a new project -- it probably has capabilities we
would take advantage of if we could (who knows, maybe we could generate
indexes?).
I hope this is helpful. Feel free to ask more specific questions.
Kim Haase
On 08/18/10 04:56, 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?
What are the problems you've found?
Are you able to do it with just free tools?
Is it overkill for a "small" OSS project? or is the extra hassle worth it?
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
