I’m trying to write a pretty simple web application. All I need is a programming language, database engine, coding framework, CSS framework, Javascript framework, ORM tool, template engine and a web server. Simple, right? Most of the tools I chose because I’m familiar with them and have enough experience to get started quickly. There are a few though that I’m still learning. It is here that the value of well written documentation has become VERY clear to me.
I decided to give Kohana a try. It is an open source PHP HMVC framework that I’m interested in leaning more about. I’ve used it a little, but this will be my first full site using it. I decide that I want to leverage as many tools as I can to get the site built quickly. This is as much an experiment in learning new ways of doing things as it is a desire to use other people’s code.
Without going into the gory details let me just say that Kohana is a PHP framework that split off from Code Igniter (another PHP framework) because the Kohana developers wanted a community driven site and faster adoption of PHP 5 OOP. Since then, Kohana itself has forked such that there are 2.4 and 3.0 versions being developed in parallel. Although some progress is being made, the Kohana 3.0 web site and documentation are seriously lacking. The communities’ response to date has been either “search the forums” or “review the code.” I will let you make your own judgment on how effective this will be in speeding Kohana 3.0 adoption by the community at large.
Kohana has an ORM. Great, right? Not so fast. Kohana’s ORM was written by one of the core developers. He has since written a new ORM (called Sprig) that he feels is his best attempt to date. The original ORM is still there and is supported by one of the other Kohana developers. The interesting part is that I have to assume he wrote Sprig to overcome some limitations he perceived in Kohana ORM. I don’t know what those are, but they must be there, right? Anyway, the documentation for ORM is pretty well fleshed out. The documentation for Sprig is spartan, but what exists is well written and easy to follow.
Worried that using an ORM solution by one developer with patches coming slowly was a bad decision I went out exploring the many other PHP solutions that exist. One of them caught my eye. It was RedBean. RedBean is a new ORM. It has some really compelling features, but what really drew me to the product was the documentation. They wrote a quick start guide that is excellent. Their manual is also not too shabby. Ultimately (and much to my disappointment) I discovered that RedBean had what I deemed an undesirable strategy for managing relationships. This was a great blow as I really found it one of the easiest and best thought out products I’ve yet to encounter in the software world. More importantly, RedBean’s documentation is second to none for it’s concise and well targeted content.
So what is the point of all this. It’s simply that documentation, good documentation, is necessary for rapid adoption of any solution. You can build the greatest product of your generation, but if the developer community can’t figure out how to use it then the effort was wasted for all but a precious few insiders. I know how to read source code and I’m not “afraid” of it as one Kohana forum member posted. The problem I have is reading source code is the LEAST efficient way to learn a new solution. Documentation that is well structured, brief and to the point and has relevant examples is as valuable as the solution itself.
I understand that these are volunteer projects and that coders want to code. I’m only saying that they need to partner with writers and teachers who can bring their hard work to the masses. I appreciate each of these individuals greatly for what they do. I just know that without good documentation, their efforts may ultimately be marginalized. That, imho, is the greatest threat to the open source movement. Accessibility or obscurity.
