On Paul Jones' weblog today, there's a posting concerning a possible new way for people to learn to work with PHP - Code Tests as Code Tutorials.

Early in the development of Savant (back when it was HTML_Template_Dummy) I broke the assign() method without knowing it, then distributed the source to early adopter testers. Of course, they discovered the break right away. Embarrassed, I wrote up a quick series of "visual" test scripts to run on each release. They are not automated; basically, they instantiate Savant and print out the results of various method calls, which I then eyeball to look for problems. While not optimal, and certianly not "best practice," it's good enough most of the time.

However, such "eyeball" tests seem to have an unexpected benefit. [...] Well look at that. I wrote up code examples and I didn't even know it. While it's not documentation per se, it appears to add a lot of value to the package.

It's an interesting idea, but I'm not sure that it's really a good way to go. Tutorials have a certain accessibility that you miss when you're just looking at the code. Granted, it is a nice way to understand how a package works on the inside, but I just think it's more trouble than it is worth. What do you think? Voice your opinion...