I was going to write a very angry and very long post about documentation, about how documentation is provided generally and why it doesn’t work. About the kind of mentality that drives programmers to again and again write documentation that drives other developers crazy. I wanted to give a couple of examples taken from the 2 open source projects that I have easy at hand: Drupal and YAHOO! YUI. And I was getting more and more angry as I ploughed my way through my current Drupal project. Then I realized that it would not have done much good to pour out my wrath onto the waves of the net just to add frustration to more frustration. So I decided to do something more constructive and possibly to enhance the net with a piece of documentation as I would have liked it.
I hope though that someone will also get the point of why documentation should be done differently.
How (not) to write documentation
In brief, I’ve come to the conclusion that there are two major reasons why documentation generally sucks:
- Wrong assumption about who is using it
- A bottom up approach
Often the 2 reasons are both present
1. Wrong assumptions
It is understandable that it is difficult to guess who the reader might be, the reader on internet might be anyone and in many cases she or he will belong to the ”wrong” target. However, statistically that should leave me with a great amount of docs that are all too easy to use, as I’m no longer a novice, I’m no longer an intermediate, well yes I’m pretty seasoned and been through a lot. How come then that it still happens to me to use way too much time to find what it appears to me as the sheer basics in order to be able to use a piece of software.
Often there are just no assumptions at all about who the user is, the authors just spit out all what they have in their mind in the hope that the more the better (no it is not like that, I know, but it feels like that).
2. Bottom up
Bottom up approach is given naturally by the use of documentation systems (javadoc, doxygen, phpdoc you name it). It’s fine and swell, all your functions and methods are there on the web, all class relationships are documented. That’s great, you didn’t forget any field and neglect any method or class, then it is complete.
What are you complaining about?
What am I complaining about? The contributors have also written lots of examples from where you can monkey code all the way, “cause you are a monkey aren’t you?”
Actually I am a control freak, I want to know why I’m doing what I’m doing, I want to know that what I’m doing cannot be done another way and, if it can be done differently, that there is a reason why I’m doing it this way and not the other.
Also, I want only to do what is absolutely necessary, not one line more, no more complexity than it is required by my goals. To be able to do this I don’t need to be told how to do this and that (although that also comes in handy).
Where are stairs, elevators and ramps?
What I need, is to have an overview of the whole system; I need to know the architecture.
When I know that the building has both elevators and staircases, I can decide by myself whether or not I need to know the staircase dimensions or the elevator’s capacity to choose the one or the other. Telling me every single detail about, say, the elevator, won’t do any good, if you don’t let me know that there is also a staircase, and maybe even a ramp all around the building. Still less useful will be to describe the bricks the building is made of, or the wonderful new material the whole thing is built with.
When I have this knowledge (elevator/staircases), only then it will be interesting to know the elevator door orientation or whether the staircase is straight or spiral and all the other details. And one thing is for sure, what I need to know will always proceed from general to particular aspects. Top down, not bottom up. Following a hierarchy, not a sequence of topics, however systematic it may be.
I find the building metaphor pretty good to use as a double check to see whether your documentation project is living up to my (or many’s?) expectations.
Now, what triggered my anger this time was the need to write a Drupal module. There are gazillions of pages on the Drupal site that document Drupal, and yet I’m not satisfied.
And it seems I’m not alone (some examples here):
“…and the documentation was sparse at best, so it took me quite a bit of digging to find that it was really this simple to do…”
“…Its sad to say that I seem to learn more from people’s blogs like this than from the official docs / handbook…”
“…After 2 hours of digging around, sorting through posts with no replies, and getting quite frustrated, I found out what I wanted could be done in just a few lines of code very easily….”
Here is how I would have expected to find some documentation about: How To Write And Manage A Drupal Module (link to new article to come in a very near future).