Paul M. Jones

Joakim Andersson has some honest and forthright responses to my earlier post where I state that "Documentation of code is the responsibility of the original coder." I want to take his points one by one; they deserve special attention because Joakim has been very clear and direct about his position, and I think they serve as an excellent sounding board.

The following quotes are from Joakim's comment on my blog post:

You can't say that it's someone's responsibility to write documentation. There can't really be a law that if you publish code to the public you have to also write proper documentation for it ;)

I agree, although I think Joakim misunderstands my position. I say this not so much as a command ("You must document!") as a statement of expectation ("If there is to be documentation, the coder must understand that he is the one responsible for creating it.") I say this because far too many coders misunderstand the nature of their relationship to their user base. (More on that in Part 3 of "Document Your Project Already!")

Of course it would be good if there is documentation and yes, the original author is in a good position to write it because of the intimate knowledge of the code. However, my opinion is that code without documentation is better than no code at all.

If just one single person finds the code, figures out how to use it, and use it in some way. It's useful to publish the code. If there were 50 persons who found the code but couldn't figure out how to use it due to the lack of documentation they are not worse off compared to if the code wouldn't have been published at all.

I agree on both these points. Code with no docs is more useful than no code; docs with no code is planning, not code. However, with documentation, more people will be able to get started with and make use of the code. In turn, users will be better able and more willing to contribute back into the code. This serves both the author and the userbase.

In addition, the very act of writing documentation will make your code better. When you start to have to explain, in plain terms, what you have done and why, you will realize all the little inconsistencies in your API, all the little assumptions you have about the code use, and many other little things that all add up to a higher quality piece of work.

Documentation, in short, is not only for the user's purposes; it is in the interest of the coder for his own purposes.

Joakim also wrote a blog entry of his own about my post. I now quote from there:

I agree that the low standard of documentation is bad but I believe that he misses the most important point:

It is not fun to write documentation.

Joakim, I promise you: I have not missed that point. Documentation is hard work; a different kind of hard work than writing code, to be sure, but hard work just the same.

As soon as the fun turns into a must, it's not fun anymore and the probability of it getting done goes towards zero. As soon as I start to feel that I have to write documentation, I'm basically doomed to fail with it.

Paul also states that "I'm too busy to write documentation." is not a valid excuse. However, it's not as simple as that. Take a lack of time and combine it with a lack of fun to write documentation and you have totalt disaster.

Again, I understand this completely. However, my point (as stated above) is not "You must document!" but that if documentation is to exist, the original coder is the one responsible for it. If other users create it, wonderful; if somebody writes a book about your code, great; but if nobody steps up to write documentation, the coder has no cause for complaint, because the original coder is the one person responsible for making it happen, nobody else.

I am not saying that Joakim is complaining, because he is not. His position is honorable and honest:

I'm the author of The Ismo PHP Framework and as can be seen from its documentation page the documentation is next to nonexistent.

The food on my table I earn by working 40-50 hours per weeks at my day job (not PHP-related in any way). Subtract some more hours for going to the gym, going running, meeting friends, playing with the cats, etc. What's left is like 5 hours / week tops which I can spend on my spare-time projects.

Notice that Joakim does not blame his users. He knows there are no docs, he is unhappy about it, but at the same time is not motivated to write them. With any luck, Ismo users will want to contribute, but until a certain critical mass of users exist, there won't be enough people with enough knowledge to write useful content on the Ismo wiki.

Given a couple of hours in a week, do I rather spend them enhancing the AOP (Aspect-Oriented Programming) support in Ismo which is fun, challenging, and very interesting. Or do I spend the hours writing documentation?

I think the answer is easy and one reason why open-source projects often lack decent documentation.

The answer is easy; it depends on what you want. If ("you want more people to find Ismo easy to use and get started with") then ("you will spend your time where your sentiment is and write documentation"). Any other answer says to the world that going on to the next bit of code is more important to you than making the previous bit of code more approachable and usable.

We just have to find a remedy. Using a wiki is a step in the right direction, but it's not the magic solution.

I agree. To quote Fred Brooks, author of The Mythical Man Month, "There is no silver bullet." There is no remedy other than discipline and professionalism: difficult though it may be, express your pride in your high-quality work by writing documentation for it. Your users will benefit from it, and so will you.