Summary: “Too lazy, don’t seriously care, not invested enough, or just simply can’t from the lack of programming experience. Someone else doing the documentation writing can gain a lot from the experience, but advocating someone else to do so is a lost cause.”
Reasoning for complaining about documentation
Someone once told me, “…when reading a book, if on the first page you find more than ten words that you don’t know then the book will be too difficult to finish reading.” Same deal with code, if you have to look up the majority of what the function does, then you’ll spend far too much time and eventually give up.
Therefore when someone complains about the lack of documentation, they are really saying that they don’t understand the code and wished there was language that explained what the function does and how to use it. They shouldn’t have to understand what is in the function, only how to use it in their code.
Documentation in open source projects isn’t just for you when you discover the code again months down the road. It is for the little guy that doesn’t understand as much as you. Everyone started out not knowing everything and documentation needs to be there to help them along.
Who should write documentation?
The person that should be writing the documentation, whatever the style, should be the person who wrote the function in the first place. However, writing documentation just isn’t sexy and usually, you almost spend an equal amount of time writing the documentation as you did writing the function. (At least that is what I’ve generally estimated for myself and usually it takes longer to add in the extra touches that the developer using the function might want to know.)
If documentation doesn’t exist beforehand, then it is everyones game with writing documentation. The issue, I believe in reading past discussions, is that people are either too lazy, don’t think documentation is sexy enough, or too conflicted with whether they should spend the time.
The people that wrote the PHP Language documentation are gods. Wouldn’t you want to be god too? Even if it is just one function, that is one less function that someone needs to look over to know what it does.
Benefits of writing documentation for another project
Code review gives another pair of eyes on the code to point out any flaws that might not have been apparent to the original programmer. “Hey wait a second, that isn’t right!” In which case, if they misspelled a variable, that bug might never become apparent until someone stumbles upon what is expected verses what actually happened. Something that might never happen in some edge cases.
Better learn about how to write documentation. Dude, it is awesome, because you can take the blood, sweat, and tears working on an open source project to another job and reap the rewards. “Yeah, I wrote documentation for such and such popular open source project.” Also, the experience is always useful to become a better writer and gain feedback and insight on how to help others.
Refreshing. Yes, quite and no I’m not being sarcastic, “What? It is midnight already? Just a few more hours.” I’ve been enjoying myself documenting another’s project. Time just goes by and I lose myself in the hell that it is. It is also interesting to see what paradigms and patterns the project uses. Learn from how they do things for how you can further use it in your own code.
Gratitude from those that know that you wrote the documentation. You won’t be the superstar that actually wrote the code, but you’ll have the respect from those that have to use the awesome code those superstars wrote.
Conclusion
It takes a long time to write documentation and unless you have a vested interest or are really hardcore, you could really care less. I’m tempted with writing PHP language documentation, but it just isn’t as sexy as actually writing PHP code.
Likewise with other developers, they might be able to write the code, but spending the time on something boring verses something fun like writing code. I think we know which one wins most of the time.
The brave and the few that write documentation for any open source project have my respect, even if I don’t know who they are.
Possibly Related Posts:
- Bullet: E-Book Library Management and Content Server
- Using ZendFramework 2 beta1 For Directory Project
- The Way of Kings and Cosmere Theory
- “In Time” Movie Premise Flawed
- Completing HTTP Library For PHP
I had my own thoughts on the challenges of documentation a while back: http://www.garfieldtech.com/blog/documentation-problem
What I am referring to is API Documentation. The other documentation is needed, Wikis and DocBook documentation are good for Beginner Documentation and Programmer (what you can training) documentation.
In that sense, when I write API Documentation, I want to combine Beginner and Programmer aspects that you describe, but I realized that phpdoc isn’t the best location. Rarely are non programmers going to crack open the hood and see what runs the engine. That place is dark and scary and often without context.
I agree with you, but it is difficult to give context to everything and every solution. Although, that is impossible anyway, the goal is to describe how it can be done and allow for the user to go off and contemplate what can be done.