Some weeks ago, I had to start investigating a new technology (dita, but that is not really important) in the context of a customer project. In addition to being unfamiliar (even remote) to me, I discover it to be rather unknown by the community, something that had not happened to me since quite a long time. I try to share here some findings about the experience.

What is happening?

Image representing Stack Overflow as depicted ...

Used as any developer to the learning process, using something I do not know was actually mostly a good news: it is an opportunity to learn. I started with some queries on google (“getting started with dita”, ”dita tutorial”), contacted the developers in my network, looked for books on amazon (at least to collect titles) and generally for blogs, forums, or others. I of course searched for a tag on Stack Overflow (if you are the last programmer on earth not knowing about Stack Overflow, click on the link, and get back when you are done. It will probably be in a couple of years, but that is ok, it is more important than reading the rest of my post, I’ll forgive you).

And this mighty harvest brings me... A very few little snippets of knowledge. Enough to start something. But not enough to get help when things began to get off-rails.

A given

I realized that since some years, I’ve started to take the community as a given. Community in a very broad sense: people, but also (mostly) production such as blogs, tutorials, public projects, and especially Q/As (as many people, I read much on SO but do not post many questions - most of mine can be found with a search, and I can just read the answers that matters to me. Less noise and duplication on the site, less work for me. Double win).

Call that laziness or complacency if you want, but I lost the meaning and thrill to debug or browse the source code of libraries I want to use. I tend to use libraries as they are (often) efficient tools that allows me to build faster and better. If you want to build a house, starting by building each and every of your tools (and cooking your bricks) make no sense (the process is certainly enlightening, but if the goal is the house, it is no strategy).

What it gives

What the community gives you is not recipes to be blindly followed (well, so does, but it is not what most of us are looking for), it is something bigger

George Resse's talk at devoxx

and more complicated than that. It is real world usages, sometimes with the linked story about what worked for someone and what did not - and if you are lucky, why.

It is experience, trials and errors followed by advises using this knowledge. It’s the road travelled, good or bad, often somewhat in between.

In a nutshell, it is a whole set of knowledge that you can decide to pick when needed, and deep as needed. From the “how do I run this thing” to “here is my custom patch for this very very rare scenario that I’m probably the only one to need”.

To get back to my somewhat provocative title, it does not means that every popular library is technically sound or well designed, but once it is popular its flaws (or more reasonably, its opinions) become very visible, allowing you to pick the right one (for you) quite easily.

In a world where we build software to get value to people in a reasonable amount of time, it is of great value. I love as much as any developer the nice design and the sheer joy of understanding a given technology inside out. But, most often, if the result matters, this is not the right level of understanding - you cannot invest that much in each and every aspect if you want to put your software in the hands of the people that need it. And I do.


Even being (almost) alone, with no specific knowledge does not means there is no winning strategy. As for any technical problem, it comes down to very generic principles:

  • Find a working example, find some way to validate that it does work (some of the problem that you’ll find are most probably linked not to the sample, but to your misuse of it). Ideally, your “test” should not require more than one command or click and a few seconds (as you’ll want to test all along the way).
  • Trim it down gradually to the smallest, most limited case possible, testing it all along the way.
  • Adapt this very simple case to your need, to make it your smallest possible use case.
  • Start building on it, testing on each iteration.

In three words: divide, test, conquer. I cannot emphasize enough the testing/validation part. The less you know about a problem, the most (and most often) you need to test it.

Do this work? Yes. Is is efficient? Barring other means, yes, but half a dozen examples or Q/A would have lead me at this point in less than half the time. Still, good reminder that this happen, even outside the academic or highly technical domains.

Hey, dita is not that complicated/obscure!

So you know about it? Good news for me. I would still appreciate an exchange of views on the subject, should you have some precious emails or Skype

Some Light Reading on DITA

minutes available. Various ways to contact me are spread around this website.

Now, I did not want to go into specific points, as this was not the purpose of my post, so I kept the exact library somewhat on the side. This is of course only my personal experience, but what I’ve found is that dita is quite obscure, at least on the implementor side (the user/writer/publisher side is better furnished). My needs are various use cases of specialization/customizations, and on those, I found:

  • 91 results on Stack Overflow, one of them specialization related. Compared with the “normal” SO activity, those results are very low.
  • One active mailing list where a resident and really helpful expert try to help as many people as he can. But he only got 24 hours in each day.
  • One well written tutorial about specialization. It is well done, really. One. The SO answer about specialization point to it.
  • I consider myself reasonably well connected in the IT word (at least in Belgium). I did not find anyone with experience above “used it”.

For a technology that is not so new, it is still a very small amount of info. Even with that, I must say I’ve found dita full of interesting ideas and concepts, and will probably use it for my customer needs.

Enhanced by Zemanta