Why Writing Documentation Wasn't a Waste of Time

The hardest part of writing documentation for WordPress was coming to grips with the realization that I could have been spending that time actually doing something. I put aside three browser based games, a library I was working with someone on, and my core web sites to write inline documentation. That I think was a tremendous sacrifice or so I thought at the time. The motivations for which was that I was helping myself by not having to figure who what each function did, what function I should have used, and where each function was located. Working with WordPress was filled with so many WTFs, I was almost screaming out loud instead of just inside my head. The API in WordPress is so large, learning it is almost like learning PHP. In fact, there were quite a few times, I built functionality that already existed or to need a solution and find it one or two weeks later. Other parts were so convoluted in functionality, it wasn't worth tracking down each code branch to figure out what was happening and how I could hook in and change it.

The Codex is great for what it is and continues to be, but it is a community project and much like WordPress is an Open Source project, they both suffer from the same problem. Motivation and the surplus or lack of it. Writing documentation for the codex is a massive project, because you have to explain things so that people can understand. Writing inline documentation, you have no such restrictions.

Inline documentation is technical and to be read by programmers of various skill levels to provide the additional information for understanding what the function is used for. Furthermore, each function, object, or documented code is independent of everything else. With Codex pages, often you must tie in multiple functions to explain a given concept well enough for the layman to understand how they may be used together to create something great.

So, my motivation was that since it would take a fraction of time verses writing Codex information, it would be better to have completed inline documentation that changes with the code than to spend forever writing Codex documentation that has to continue to keep up with the changes of the code and will have a harder time keeping up to date with the code changes after the page has been written.

I believe with the introduction of books that WordPress may be served better by those who wish to write documentation for money than the community benefit. Well, each really will serve each other. Authors of books will have a limited space and thus may only devote as much as they can towards certain topics that help the reader get into the flow and basics of working with WordPress. The Codex goes into more technical information for various subjects dealing sometimes with topics outside of WordPress, but dealing with WordPress. For example, hosting, mod_rewrite, and other hosting techniques that can be used to enhance, secure, and improve the WordPress experience.

Actually, I should note that there were quite a few patches that gave me a leg up during the early parts of the project and towards the end people did help. Now that I've done other things, there are still people maintaining the documentation. In the beginning, I had the feeling that everyone wanted someone else to write the documentation, because no one wanted to be tasked with such a long and tedious project. When the choice is doing something you enjoy verses something that doesn't benefit you but other people, then well it is understandable. My prediction was that once someone had put for the effort and completed enough to set a standard of quality, then others would join.

The problem is that when you have a culture that doesn't have an emphasis on writing inline documentation, then few will do so. It is not fun writing inline documentation and is often a lot of work. Also, it would have felt like pushing back the waves of the ocean, so yeah. People can see the benefits and it is easier to continue once most is already documented.

That isn't to say that it is perfect, people still need to work on the inline documentation, to improve it, to ensure that the documentation doesn't become outdated from changes of the function, to make sure that undocumented functions are documented soon after and to make sure that future functions are documented before they go in. WordPress may have started with very poor documentation, but it would have been a lot easier to improve the documentation if the decision was made 4 or 5 years ago rather than 1 or 2 years ago. Going foward, it has to be up to every contributor to ensure that WordPress continues to raise to 100% of every function, class, etc be documented and maintain at least 30% LOC to Documentation LOC ratio.

For the project to go from 4% to 8% ratio 31% is nice, very nice. It also took a while to get there. What I benefited from it? I benefited from the experience and knowledge with the ability to write phpdoc docblock style comments without needing to look up what each tag does, what it will look like, and how it is used. It speeds up my ability to write inline documentation and thus I write more of it in my own projects. I'm finding that it wasn't a waste of time and that it has and will serve me well in the future.