VICTOR: I like to write documentation.
CHORUS: Hello, Victor!
There it is. I have admitted it. Yes, like most programmers having suffered under heavy waterfall-like development processes, I still prefer running software over documentation. But whenever I get to work on a project with an existing code base, I really like to have some document that explains the most important concepts, the decisions and the influences, which lead to theses decisions. And I do not mean a reference documentation, like JavaDoc. That is helpful (if done right) but you need to understand the code base before a reference documentation can help you.
Even more important, when I am starting a new project, writing something down helps me to clarify things in my own mind. And giving these drafts to other people makes it easier for them to spot the gaps in my reasoning. If I only have some pictures and scribbles on paper, I can wiggle myself out of the tough spot with eloquence (or what I consider eloquence) and some hand weaving. I am good at that.
Writing forces me to think things through. And writing it down with a reader in mind helps me get the priorities right. I once had a summer “job” where I had to explain board games to other people. As fun as that sounds, explaining games really is a good training to tell the important things first, to put yourself in someone else’s shoes. I still think this experience helped me become better at communicating – but writing is still a challenge.
When to write
We may discuss, when we should write documentation. I still prefer to write most of it after the implementation. Because then I am quite sure to get it right. But if there are multiple parties (vendors) involved or if it is part of a proposal, it has to be written before the implementation starts. You may call that “specification”, but for me it still is a kind of documentation or it should become part of the documentation.
Which tool(s) to choose
Now that’s where things get difficult. I do not know. This is one reason, why I am writing this piece. If I write everything alone, but someone else must be able to edit it, I still propose Microsoft Word (TM). Yes, it still has its quirks (never use a floating text frame. Never!). If the document is mostly text, I really love MultiMarkdown. It is fast and simple to write (even on my iPad, like now). Being able to get beautiful documents in LaTeX is one of the major advantages.
But. But MultiMarkDown has only that many supported styles. What if I need a style for Shell output, and a style for class and method names inside a paragraph, etc. I can use “native” markup in LaTeX or HTML. But not for both. And it makes the readability of the text I am writing much more difficult. The beauty of (Multi-)MarkDown gets lost, if there is too much markup in there.
I cold still switch over to LaTeX. But here comes the rub: Not too many people are willing to switch with me. In many projects it has to be Word. I might be able to sell MultiMarkDown but not LaTeX (not to mention DocBook, which is really awful).
The biggest problem with Word: Merging.
You can get around many problems with Word, if you force everyone to only use styles. No manual formatting! You can even mark every manually formatted text.
But if you have to write a larger document with multiple contributors it gets really difficult. Merging in Word got better, but nothing compares to a really good editor that is capable of supporting a three-way-merge. Sigh.
I recently came across Ulysses, which sounds exactly like what I was looking for. You can add your own styles (you just have to define the delimiters and the transformation into LaTeX and HTML). You can even create Word documents (but without styles). … if only there were a Windows version.
I am currently thinking of extending MultiMarkDown, but I still hope someone has a better solution …