TNBT: Documentation Sucks

Documentation is the unloved step-mother of software development: Nobody likes it.

On the writing side, documentation is either considered a waste of time:

• I could write code in that time
• It won’t be valid anymore after the code changes tomorrow, anyway
• There is no way to make sure you can trust documentation
• Stringing sentences is hard work, especially when you want to make them easy to read, understand and interesting to follow.
• It’s hard to connect code samples with documentation
• If I describe too many details, readers will be bored. If I omit too many, they will be confused. There is no way to know which level of detail is good.

On the reading side, it’s a waste of time:

• I need to solve a problem, I don’t have time to search in a huge dump of text
• If the author doesn’t trust the documentation, how can I?
• It will contain too many details that I already know and omit too many facts that I need to understand what is going on.

The core of the issue is that documentation and code are two different things. Documentation is, by nature, abstract. It’s at least one step removed from the solution.

But the question should be: Does it have to be that way?

I hope, with new technologies like Xtext or JetBrains’ Meta Programming System, we will eventually be able to turn documentation into code.

So instead of writing hundreds of lines of code to open a window, give it a size, make sure it remembers its size and position, etc., we could write:

Allow the user to edit a Customer object which has properties from foaf:Person and one or more addresses.

Users can search for Customer objects by any of the name fields.

Note that the links are part of the documentation and the code; the underlying code generator should follow them and examine the code/documentation on the other side.

Related Articles:

• The Next Best Thing - Series in my blog where I dream about the future of software development
• The next challenge for Software Engineering – Daniel Ford also wonders how to improve documentation