wuetender-junger-mann.de

I am currently for a large organisation that seems to embrace DITA for their documentation. In theory this is a nice thing. There is a wealth of tools to edit dita files and to transform them to all sorts of formats. The reference implementation is the DITA OPEN TOOLKIT. First of all I am not impressed with the documentation. There is no proper tutorial and no good overview. And these are people who are into writing documentation!

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.

What troubles me with java is, that the implementors of its standard library utterly failed at setting an example. Java developers don’t know how to do proper christian oo, because every time they peek into the library sources they see C-ish hacks.

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…

There is a lot of nasty stuff to be said about velocity, but today I complain about it’s stupid whitespace-ridden syntax and it’s equally stupid error messages. I just got this one:

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