Documentation and DITA: The Derby Experience?

[Alex McLintock <al...@gmail.com>]

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

Re: Documentation and DITA: The Derby Experience?

[Kim Haase <ca...@oracle.com>]

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
> 

Re: Documentation and DITA: The Derby Experience?

[Bryan Pendleton <bp...@gmail.com>]

> I've been recommended to look into DITA and can see that Derby uses it
> for its documentation.

As an ordinary Java developer (that is, I'm not a full-time tech writer), I've
found that I can successfully build and maintain the Derby documentation. I
don't have to use many special tools; for the most part the tools are the
same as those I use for my ordinary development (Vim, Ant, svn diff, etc.)
All the tools that I use are freely available.

However, we are blessed on the Derby project to have several professional
tech writers who are regular committers, and I think that when the initial
Derby documentation was set up, there was a pretty substantial effort to
construct the initial docs implementation. So I am benefitting from those
situations, which perhaps are special to Derby.

DITA seems quite powerful, and yet the actual documentation that you write
and maintain is just some simple marked-up XML files. Feel free to browse
the Derby docs source tree to get a feel for what the typical DITA source
file looks like in Derby. For example, here's a random, yet quite typical, file:
http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefmonthfunc.dita?view=markup

I'd pretty much have to call our docs setup a complete success, with the
caution that I mentioned above that I suspect the initial setup was rather involved.

Hope this helps!

bryan

Re: Documentation and DITA: The Derby Experience?

[Rick Hillegas <ri...@oracle.com>]

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