22 Jul
What Is Really Considered Documentation?
I struggled to come up with a good name for this blog post, and have totally failed, but give this article a chance. Or maybe you’re here by accident thanks to a weird google search.
As a committed user of open source technologies, the difference between me using something and not using something is the documentation. Is there documentation for it? Is it easy to find? Does it answer my questions? Is there someone I can call an idiot if I disagree with the level of documentation? These are all very important questions.
My involvement with CakePHP has opened my eyes in terms of what people consider documentation. Me, I’m the type who learns from examples that come with explanations. While API documentation is great, it only becomes useful to me once *I* can figure out how to do something useful with this new technology. I see people on the mailing list for Cake asking for the source code to a sample application, which I immediately file away in my head as “looking for answer to their homework”, and move on. Maybe that’s unfair, but it’s more a reflection of the fact that I tend not to learn anything from having the source code for an application. I learn by getting in there and DOING SOMETHING and figuring out why this goddamn thing is not behaving properly and who do I know who can help me with this problem etc. Learning by mooching, I call it.
So, back to CakePHP. CakePHP had acquired the reputation that the documentation for it sucked. While I did not share that opinion, I can see why people say that. Because most coders are lazy. Seriously. They want solutions handed to them in a form that they can just drop into their application and then get onto the next problem. There are definitely times when I wish someone else could just write this goddamn “alter the football game stats form dynamically via Ajax and send the results to the XML database” code for me. Inevitably, I build the code up from an example stolen via Google into something that both works and that I understand fully. However, most of the time I am content to figure stuff out on my own and ask for help only when stuck. I’m not lazy, but maybe I’m suffering from a bit of the Lake Woebegon effect.
So, things are much better in terms of documentation for CakePHP. Whereas we used to have a manual that only covered 1.1, we now have the amazing CakePHP cookbook that covers both 1.1 and 1.2. If that’s not enough, well, you might actually have to do a little thing I like to call “research”. This gets us to the point of this blog posting. Sometimes you have to stop being lazy and actually think about where you could find an answer.
There are no shortage of blogs that talk about CakePHP. Some of them are even good. Maybe you like the code examples I put up here. People seem to like them enough to comment, so maybe I’m doing something right. Google is your friend to track down blogs that have exactly the type of information that you need: small examples with explanations about how they work.
The CakePHP mailing list is done via Google Groups, so all those posts where I make fun of people for no reason other than my poor self-esteem can be found with a few keywords. But there are a lot of great tips on how to accomplish things using Cake, so a search of the google group will find lots of good information.
The Bakery is another good source of CakePHP info, consisting of all sorts of small articles along with comments. It has a search function as well, but could easily be considered YACB (Yet Another Cake Blog). Again, perfect for people with the same learning style as me: short examples with explanations of how it was done.
Finally, we come to one of the more unorthodox documentation sources: the unit tests for CakePHP. CakePHP has some really good unit test coverage, although I sometimes wonder if you can really say that a piece of code works properly if it passes all the unit tests associated with it. This is by no means a phenomenon limited to CakePHP, it happens everywhere there are unit tests. Sometimes you can’t figure out a test that makes something break. It happens, so please do not misinterpret my thoughts on this. Unit tests are good, and the amount of tests that CakePHP has in place is awesome and perfect example of a cohesive development team. Automated testing is a goal worth striving for, don’t let anyone else tell you otherwise. I’m in the early phases of automated testing for a work project on the integration side of things because I’m tired of always running through the same damn tests by hand all the time to make sure something that I wrote didn’t break things. Tips on what good browser-based solutions are out there would be appreciated. Other than telling me to use Selenium. A solution that is tailored to the framework I have been forced to use would be even better.
Okay, back on topic. Since the unit tests cover so much of what CakePHP can do, what better way to see examples of how to actual do things? My work on fiddling around with new console functionality showed me that I had no idea of how to create unit tests for my console work. That led to discussions with people on the best way to do testing of console functionality. Which leads to changes in the console code itself to make it easier to test certain things. But at least when I’m ready to get back to doing that console work I can see if doing testing for it has become easier.
So, having been told all the stuff above, how can anyone who is not simply lazy say that the documentation for CakePHP sucks?!?
Article Tags >> CakePHP || Chris' Brain || documentation
Posted by José Lorenzo on 22.07.08 at 9:46 pm
I totally agree with you. Back in the days it was a little bit difficult to get documentation on cake, but I like to learn by trying myself and reading code, so I always got a solution one way or another. Reading cake’s core code is one of the best things I could have done for improving my own and to learn the internals of the framework.
I think that the current cake documentation is extensive and impressive, the cookbook is huge and more detailed than the Code Igniter one.
As you say, programmers are lazy, googling for answer is almost sure to bring you to a solution, and there are plenty of cake related blogs with hundreds of examples. I wonder why people still are complaining about cake docs!
Posted by James on 22.07.08 at 9:46 pm
I do not think the documentation for CakePHP comes anywhere close to being bad, or sucking in any way. Anyone who thinks so, really hasn’t come across terrible documentation before (Joomla - I’m looking at you).
My biggest problem with CakePHP’s documentation is that much of the literature is confused, and in some cases contradictory, or missing critical details. A prime example is with the ACL implementation. There are hundreds of articles on how to use it in CakePHP, but they all say something different, and some of the techniques are outdated, or have been changed since the article was written.
The ACL section in the cookbook is also guilty of this as it doesn’t cover the full scope of the ACL component and how it works together with Auth.
Another thing is HABTM documentation - again, contradictory and incomplete.
That said, eventhough it’s a bit of a headache getting through these hoops, you can always rely on the well documented API, and even the comments in the code itself are helpful. Most problems I’ve ended up solving just by reading the code of the function(s) I was trying to use. CakePHP’s source code is generally very well written and easy to follow.
The Bakery is a great resource, the cookbook is always improving, and the best part of the CakePHP documentation is that ANYONE can get involved. I’ve contributed to the bakery and have submitted stuff to the cookbook. If you learn something useful about CakePHP, pass it on!
Posted by Micha? Szajbe on 22.07.08 at 9:46 pm
Well, I share similar view on that topic. I look into cookboks, tutorials and guides just to get general view of the technology I am learning and then stick to APIs and google. For me APIs are the most comprehensive source of answers to my questions and I use them every day. Reading the code itself is also very educative.
I can’t remember when I last time asked a question on any mailing list or forum. I can google it much faster or get an immediate help from co-workers. I have no patience to wait for the answer that may even never arrive.
However I have an uderstanding for people that have different approach. You need some time to develop an answer-finding-methodology that suits you best.
Posted by Comb on 22.07.08 at 9:46 pm
I’m sure some of you are people who prefer driving directions as sentences while others prefer maps. Some do best with both. To take what works best for one person and assume it should work well for another is no less a mistake than shoddy ui design.
Fortunately, I’ve had a lot of experience both with designers and developers and one great errors of the stereotypical developer is “What? I get it, why don’t you?” That’s no different than zero documentation because you don’t get why people can’t just read your code and reverse engineer it themselves. It feels like that’s your primary argument here. You’ve just defeated the primary benefit of leveraging a framework. You’re forcing the end user to work at the low level instead of the high level development promised by use of frameworks.
I agree that the documentation does exist, albeit… contradictory, incomplete, and unorganized. In less than five minutes, I’m sure we can find a long list of frankly incorrect documentation in the cookbook. At least now we can go through and submit corrections. Prior to that, there wasn’t much you could do. If you need specific examples, I believe at last look prior to the cookbook going down, all the find documentation was using the findAll, etc. A browse through the bakery also yields entries which look fine until a few comments down the line someone with experience points out this is a completely errant entry running counter to cake convention or simply poor solutions.
I approached cake as an experienced developer looking to make life simpler for some basic projects. I did find the existing documentation situation frustrating because of the conflicts in the manual (and now cookbook) and the bakery entries inconsistent in quality. And folks new to the cake community have no idea which blogs provide dependable, quality solutions and which are hacks.
As for _working_ example code, it’s important because frankly developers are not the most articulate folks around and the description for an expected value or argument isn’t always clear.
I don’t think you’ll find other communities pointing to third party blog posts and such on independent sites as an excuse for not having better documentation. And that’s the biggest frustration for new users. While the community as a whole writes lots of informative posts and such, the authoritative voice (domain in this case) provides little or no direction on a number of critical topics.
When trying to quickly integrate this framework into an existing workflow, the experience could be significantly improved with more accurate, authoritative and organized documentation. I don’t think anyone would deny that.
Remember that most of the cake audience comes in as a developer crunched for time and looking for a solution. Successfully hooking and keeping that developer means providing a means to locate the right information quickly. You’re right to say that it is possible to locate the information with enough time and patience, but to a hurried developer looking for something to save him, it’s just silly.
Respectfully
Posted by derek on 22.07.08 at 9:46 pm
Conversation is for conveying what you’re going to do.
Documentation is for explaining how it works (with emphasis on the complex bits).
If you’re not going to keep a document up-to-date, you shouldn’t bother creating (unless it helps you think through what you’re about to do).
The way to do that is through automation of documentation.
It’s not the nicest thing in the world to read, but it keeps developers productive, and means you don’t need to hire a full-time documentation Guru.
Plus, automated documentation is always up-to-date!
You can use a few handy tools to generate different types of documentation:
1) PHPDocumentor is a tool that parses all javadoc-style comments out of your code and puts them into navigable HTML files.
2) TextDox is another little hottie. It creates documentation by parsing out the names of your unit test suite names & method names.
For example, if you have an AccountTest class with a cannotHaveANegativeBalanceTest() method and a canHaveMultipleOwnersTest() method, you will end up with a document that says:
Account:
- Cannot have a negative balance
- Can have multiple owners
How do you run PHPDocumentor & TestDox?
Use Phing, or Ant. Both are free and fairly simple to learn & use.
Of course, only documenting the “how” of a project isn’t always enough.
If you have a distributed team, or if you’re developing an open-source product that any Joe Schmoe can download, they’re going to need access to the original conversations. To be most effective, they need to know why things are the way they are. That’s not covered by any auto-generated documentation, and I believe this is where screencasts & tutorials come in handy.
>>I sometimes wonder if you can really say that a piece of code works properly if it
>>passes all the unit tests associated with it.
Unit tests only prove that it does what you said it would do, not that it does the *correct* thing.
It’s up to the Product Manager / Owner to define *correct*.
Posted by Peter Childs on 22.07.08 at 9:46 pm
The issues I have with Cakes documentation is the assumption that Cake users are all intermediate level programmers or better. I also think there is an the over reliance on scaffolding in examples.
There is a lot of automagic that goes on and if you’re trying to learn programming and Cake at the same time (as I am) there can be a lot of reading to fill in the missing pieces that are assumed as common knowledge in the documentation or hidden when examples use scaffolding.
Also while there are a lot of great blogs, forums and groups (and I use them extensively) I’d suggest that those should not be considered documentation in any formal sense because they lack a coherent structure and reflect a variety of (sometimes contradictory) coding practices.
In the end the quality of documentation will influence the. size and growth rate of the user base so documentation is worth investing in.
Posted by phpcurious on 22.07.08 at 9:46 pm
Hi chris,
This blog post is an interesting read. Though, I do have some complaints and feedback of the documentation on cakephp, still, I cannot say no one is doing a great job. I believe cakephp’s documentation [http://book.cakephp.org] is always updated from time to time, so there’s a chance you will see what you are looking for.
I don’t think coders are lazy. IMHO, sometimes, coders can’t afford to have time to make experiments with cakephp.
Posted by nate on 22.07.08 at 9:46 pm
@Peter Childs: Yup, a working knowledge of PHP is assumed, and nope, we don’t consider that a problem.