The second problem is the poor quality of the tooling. It a pile of ant build files, XSLTs and obscure jar files. This stuff is really brittle. Also it seems that people are not really concerned about having a decent continuous integration process. Documentation is rendered on some developer box, that has the “right” version of the toolkit installed. Clearly not everything that has the name Darwin on the box is good. The Practices of Proper Christian Programming have certainly not been followed. The whole thing is terribly brittle. Countless hours have been wasted, are being wasted and will be wasted. This is very unfortunate because documentation is often treated as a third class artefact that gets created as an afterthought using terribly blunt tools.

One decent resource is actually DITA for the Impatient. Generally I would advise to use a custom tool chain to build your documentation. Probably something involving a templating language. Transformations should be implemented in a real programming language. As a backend things like LaTeX come to mind. Also ant is actually a crappy tool even for compiling java code, so providing decent command line utilities is key for a toolkit that claims to be universal and extensible.

Verdict: Stay clear of DITA.

Today I realised that PropertyChangeEvent is not implementing equals based on its value.
It is almost immutable, apart from a stupid field that has been added for “future use”. And there is a lot
to be said in favour of immutable objects with value semantics.

This is, what I was trying to do:

ValueHolder holder = new ValueHolder();
holder.setValue("Old");
 
final PropertyChangeListener listener = mock(PropertyChangeListener.class);
holder.addPropertyChangeListener(listener);
 
holder.setValue("New");
 
verify(listener).propertyChange(new PropertyChangeEvent(holder, "value", "Old", "New"));

It is going to be messy…

Parser Exception: templates/myoldtemplate.vm
    Encountered "}" at line 19, column 101.
    Was expecting one of: "," ... "}" ...  ...  ...