d: Any packaged documentation (such as tests and READMEs)
b: API docs (such as that generated by phpDocumentor or the PHP manual)
a: Examples packaged with the code
c: Reading the source code

I avoid secondary sources as much as possible out of fear of inaccuracies which could lead to programming errors. Source code is the most reliable and is the only “truth”. Examples packaged with the code can be out-of-date. Auto-generated API docs are usually pretty good. Packaged documentation can be out of sync with the source code and examples. So if I get any problems at all from the documentation, I try the next most reliable source and eventually the source code.

But I have been burnt with this approach many times because it turns out the documentation is missing key information is or is frankly inaccurate.

So I have to read through the source code for myself and decipher what’s going on and sort of guess at how the original author meant for the class or classes to be used.

The worst documentation is where the funtion name and parameters are described but not in enough detail. Bad documentation fails to describe the datastructures which a function is supposed to accept. And bad documentation doesn’t explain how the function uses the data structure to achieve the purpose of the function, this means you don’t know what parts of the data structure you can change and what you can’t.

It is too risky to trust the documentation on PEAR because over time I have found the documentation doesn’t match the actual operation. The problem with this is that it makes it difficult to know what your doing wrong if the program isn’t working as expected.

The packages I use mainly are DB, DB_Table, Date, Mail, Mail_Queue, Validate, Auth, QuickForm, QuickForm_Controller and that’s about all I can think of right now.

This sounds like a rant and it is. I had hoped that PEAR would save me some time and headaches but it made projects more risky because the documentation was insufficient. Instead of being able to just plug in and go, I had to experiment with the code. Instead of simply learning how and when to use it and then making it happen, I did what I thought was correct according to what I could make out from the documenation, but to get unexpected results.

The point of all this ranting is that yes, now my behaviour has changed, I prefer to check the source code. BUT, if the documentation was better, I’d much prefer using that to learn the packages. Good documentation describes the data structures, the purpose of all the elements, the intended usage of functions, the intended collaboration between classes, and so on. PEAR needs more and better documentation!

Examples are the easiest way for me to learn a library. They should be very simple examples, with as little outside code as possible. Of course, examples coupled with tutorials are all the better.

I can usually learn easily enough from API docs, but the problem is, they serve better as references than as guides. A reference lists all the calls and classes, while a guide lists possible uses and explains what calls and classes to use.

I’d have to say I read source code of a class ONLY when I’m curious about how it achieves it’s results, or I wish to extend it. API Docs are great, but as Chris noted, make handier references than learning tools. Again, agreeing with Chris, examples usually lead to the highest clarity in the shortest amount of time.

g: Pair programming

Pardon my ignorance, but what’s this?

After that if there’s good supplied documentation I’ll give it a quick browse (who reads the manual anyway ;) hehe).

c: Reading the source code
b: API docs (such as that generated by phpDocumentor or the PHP manual)
a: Examples package with the code
e: Guessing method names (with IDE help) and parameters.
d: Any packaged documentation (such as tests and READMEs)
f: Online tutorial (e.g. those on Sitepoint or a developers WIKI)
i: Book chapters
h: Print magazine articles
g: Pair programming

so keep on your good work on Sitepoint :o)