3 Jul
What Do You Do When There Is No Documentation?
One of the most common complaints currently leveled at the CakePHP project is that “there is no documentation for version 1.2″. What people really mean is that there is no one central place where people who want to use the latest version can find documentation. There are examples in the bakery and in threads on the mailing list. Really gutsy developers can look at the API for version 1.2 or dive into the source themselves.
Now, a decision was made that there would be no manual released for 1.2 until 1.2 is declared stable (or maybe the API’s won’t change). Luckily you can look at an alpha version of the documentation as well. I suspect that not too many people know that you can find this information and simply assume that there is none available.
So, what *do* you do when there is little or no documentation? I’m running into this because I’m trying to use a brand-new component for authorization and access control called (oddly enough) Auth. It’s very useful…but there is no documentation existing for it. I have access to a soon-to-be-published article about it (thanks Nate!) but it’s not giving me enough to go on. I’m left to call in other favours and get access to the source code of some other apps to see how they are using the Auth component, but some of those examples aren’t working for me. *sigh*.
So, I ask you, lazyweb style, how do YOU deal with a lack of documentation for a programming component that you want to use?
Posted by Daniel Hofstetter on 03.07.07 at 9:47 pm
Depends on the available time, either digging in the source code or writing my own component. As I am rather bad in reading code written by others I prefer the latter.
Posted by Joel Moss on 03.07.07 at 9:47 pm
Yep, if I can’t figure it out from the source easily, then I give up and write my own. Which is very annoying.
Posted by Walker Hamilton on 03.07.07 at 9:47 pm
I hop into the source-pool and swim around.
I ran into a pagination issue recently and ended up completely hacking up pagination as a custom private controller method.
Posted by Juan on 03.07.07 at 9:47 pm
Read the code, or write my own version
Posted by Andrew on 03.07.07 at 9:47 pm
I look at the API and play around until it works - if it doesn’t I pester the lovely people in #CakePHP
Posted by Tarique Sani on 03.07.07 at 9:47 pm
We regularly run the latest code through phpdoc - the result is used as a starting point. However there are places when you are not sure if a feature has been implemented / complete in which case the list or IRC is a great place, thankfully most of CakePHP is written very lucidly
Posted by Dieter_be on 03.07.07 at 9:47 pm
I use Google search
if there is something ( _anything_) written about it, you’ll find it on Google search
Else, use the source
Posted by Travis Swicegood on 03.07.07 at 9:47 pm
You could always turn debugging on in your favorite IDE and step through the code that way. When someone reports a bug in SimpleTest (rare as they thankfully are), I’ll setup a test case, tell Komodo to stop before that case starts, then just step through the code one line at a time looking for where my assumptions about what the code should be doing and what it is actually doing differ.
Posted by Tane Piper on 03.07.07 at 9:47 pm
Doing a Technorati search for “CakePHP” is also a good starting point, as it indexes a lot of good blogs with people putting up their own code snippits, tutorials, explinations, etc.
I have to admit, at first I found it hard to with the lack of any “official” docs - but persevere, looking at the code and API as Chris suggests and you’ll eventually get there.
Posted by cakebaker » Usability-driven development on 03.07.07 at 9:47 pm
[...] the article “What do you do when there is no documentation?” Chris Hartjes wrote about his attempt to use the Auth component in CakePHP for which almost no [...]
Posted by Geoff Ford on 03.07.07 at 9:47 pm
Simple, you look at the source, step through in a debugger if need be, until you understand what it is doing. Combine that with a quick google search and you can sort 90% of code problems out.
Else you leave it alone and figure something else out, use a better documented third party component or write your own.
Posted by Matias Lespiau on 03.07.07 at 9:47 pm
I think that going through the api, unit testing, debugging and just asking are all nice solutions for undocumented features.
But, regarind making our own version of the feature is what I think is one of the main problems of lack of documentation.
When we talk about small stuff, usually there’s no problem. But when they are large implementations, this is a problem.
I’ve seen this a lot in open source frameworks, people create their own version of an undocumented feature, either because they didn’t understand it or because of being unaware of it’s existance.
Then people start using this feature/lib, and some members of the community join efforts to improve it. Meanwhile, the core feature grows with other people supporting it. So we end up dividing forces to do the same thing, or worst, our happy contributor is now dissapointed to know that he could have been wasting his time on something else as there is already something that does the same work.
PD: Please excuse the lenght of my comment and any language mistake i could have done.