TNBT: Documentation Sucks

11. October, 2012

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.

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:

If You Want Them to RTFM, Make a Better FM

16. May, 2012

If you’re interested in the conflicts between software and documentation, Alex Lagarde wrote a great post about that: Intent Discovery – Part 1 : the intents behind softwares.

It explains what the different (and conflicting) goals are between the “technical space” (source code), “model space” (design and architecture) and “document space” (what people need to use the software successfully). And he promises some solutions with the new Eclipse project “Intent” (and the second post in the series).

New Approach to Documentation

15. May, 2011

Documentation usually has these three attributes: It’s incomplete, outdated and plain wrong.

That doesn’t apply to every bit of information in your documentation but it you can be sure the statement above is correct for the whole documentation.

As a consumer of such documents, it’s a nice puzzler to determine into which of the three categories a bit of information belongs.

This leads to the common “we hate documentation” stance that all software developers soon adopt, no matter if they have to write/maintain the documentation or if they have to use it.

As we all know, the only reliable source of documentation are unit tests. But they can still be incomplete (= missing the example you need) or outdated (= missing examples for the latest API).

The solution? Generate documentation from the source code. And I don’t mean “from javadoc in the source code”, I mean literally from the code. If a method is used in a certain way in 317 places in your code and once in a different way, then you have two examples. One of them probably works, the other is probably documents a bug which your tests missed.

Eclipse is starting to get support for this. The first step was code completion. Now we have a couple of guys working on Eclipse Code Recommenders.

This summer, Stefan Henß starts to work on an “extended documentation platform” for Eclipse.

Thoughts on documentation

28. September, 2010

Software developers believe that documentation is just another way to say code is buggy. The reasoning is like this: If the code was easy to understand and/or did what you expected, then why document it?

While this is true at the level of a code line, there should be some documentation explaining your overall view of the world.

Next, we have end user documentation. End users have no idea how software works, they just know they have to get some work done. Stat. For them, good documentation can be the difference between a nice day and weeks of overtime.

In “The Value of Documentation in Open Source“,  Chris Aniszczyk explains why this is especially important for Open Source.  Good points.

Related articles:

Useful documentation

26. April, 2010

Documentation is one of the last unconquered areas in software development. The tools tend to get better but the documentation … well, let’s say it could be better. Why?

Part of the problem is that the documentation is written by the developers but the main reason is that they ask the wrong question. They ask “What does it do?” when they should ask “When would I use this?

Let’s have a look at an example. The OpenOffice help says for “Save”: “Click on Save or press the key combination Ctrl + S. The document will be saved … A file with the same name and path will be overwritten.”

That explains what the function does but not why anyone would use it. How about this: “Save allows you to store the current state of your work as a file in your file system. When you exit the application and start it again, you can load the file and continue where you left off.”

Aha! How about “Copy”?

“Copies the current selection to the clipboard” is boring to write (because it’s so obvious) and doesn’t answer the user’s question. Maybe the boring feeling when you write documentation like that is the nagging suspicion “this is futile”?

Try “The Copy operation allows you to save the current selection in the system’s clipboard from where you can use Paste to insert it in a different place in the same document, in a different document, or even another application if it can do anything useful with the current selection.”

Printing: “Print allows you to send the document to any installed printer. If you install a PDF Converter as a printer, you can make your document available to people who could otherwise not access your work digitally.” Suddenly, the help offers strategies and options.

So next time you document something, ask the right question.

Why Good Developers Don’t Document

10. February, 2009

I don’t document because I know what I’m doing. Seriously. I sit down in front of the computer and beautiful code flows out of my fingertips. No idea how I do it. It’s like digesting for me. It just happens. For me, with my vast experience, my code is so obvious that I can’t think of any question someone might have (okay, let’s just say I need a bit of distance to come up with questions, say a year or so). For me, it’s as simple to understand as hello world. So why make things worse by adding unnecessary comments?

I do understand that other people see this differently but that doesn’t help. I’m not those other people and I simply can’t think what questions they may have. In my case, the solution was unit tests. I need them anyway (they make me more productive) and for the rest of the team, they serve as example how to use the code I write. This is much better than documentation because

1. a test is small, so the answer to your question lies in 10 lines of code. 10 lines of code can’t take long to understand.
2. it is always correct and up to date (unlike documentation which tends to rot)
3. after getting used to test things, you feel how it improves your output (in all ways); documentation, OTOH, is always a drag (“we have to do it … not again … oh man!”).

Docs? Ask The Sphinx

16. July, 2008

If you need to generate docs for your Python projects, try Sphinx.