RE: Document Your Project Already!

Paul M. Jones has written a blog post in which he complains about the lack of documentation in public PHP code. 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

At least for me that is the sad truth. I find no joy in writing, and that English isn’t my native language which makes the writing take at least twice as long doesn’t make it any more fun.

At my day job I get paid for the tasks I do, which might including writing documentation. That doesn’t mean I’ll enjoy it but it makes it bearable. However, when I get home at 8pm after a 10 hour working day fighting with some mysterious Symbian C++ problem, the thing I feel least like doing is writing documentation.

If I will end up doing something in the evenings, it’s because I will enjoy it, because it’s fun. I believe that the majority of open-source software has been written because someone enjoyed doing it. Unfortunately I think the amount of people who like writing documentation is a significant smaller number. Hence the lack of documentation.

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.

I’ll submit myself as an example.

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.

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.

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