2 May 2008 @ 18:43:50 I've heard people complain about the lack of documentation for Solar. While I generally agree, there's something I have to say to defend Solar. There's also a few things about framework documentation in general that I feel the need to talk about.
The thing is: to really understand a framework you are using, you need to actually dig into the code and read it. That's the only way you'll ever be able to take full advantage of a framework. The framework you are using is a major part of your code, probably more important than your own code, so why wouldn't you try and learn every aspect of it? For example, I don't want to be calling methods and have no clue what they actually do performance-wise behind the scenes. At the end of the day I really want to know what the code does.
There's no denying the developers that read code are the ones that first make bug reports.
So, while Solar's manual is kinda lacky for first-comers, it's inline docs and comments certainly are not. Not only does Solar have comprehensive PHPDoc-blocks in every class and method, it also has inline comments explaining almost every line of the code. Comments aside, even the code itself is written in a manner that is the easiest to understand and learn from.
From Solar's goals:
Because reading code from other developers is a learning experience, all Solar classes are written as a teaching experience. This means that Solar classes are written as simply and clearly as possible without any tricky or obtuse techniques.
I don't see these kinds of words anywhere, at least not often enough. Programming is constant learning, even more so when you have to work with other people's code. To really learn someone's code and see how it works, you need to read the code, not read end-user documentation.
It bothers me that many companies, and projects in general, choose a framework based on how good the end-user documentation is without taking much look at the code. They look at the website and see it looks pretty and there's a long list of manual topics. At first this manual helps. It helps to understand some of the consepts and gives some hints about the API. On the long run, you will end up looking at the actual code to understand how it really works.
I've noticed many times how the manuals of many known frameworks are really vague and only touch the surface. Once you actually want to know what a method you call does, you're lost with a manual.
If Paul had put the time it took to write the inline docs to write a manual, there would be a more comprehensive manual. But there isn't. The time has been spent to write the most awesome PHP code you've ever seen, full of inline docs and comments. To me this is much more important than a manual.
You could actually pick up Solar and learn it from inside-out much more easily than any other framework. I will bet on that.
Solar 1, Zend 0
I 100% agree with you Anttih! When I started playing with Solar I was also playing with Zend and almost went with Zend because they had a large manual to go with their framework. This made me feel "safe" that I had something to fall back on if I ever got stuck coding. Truth be told that their manual really tells you nothing about the framework (well, sort of).
Even though Solar does not have an official published manual (read: a full "how-to") I find that I am better off from reading the code and inline docs not only because I understand the code better but because I can use it to its full advantage by overriding classes, extending classes, or utilizing certain data members that an official manual may not tell me about. This also gets me in the mood of the Solar framework and allows me to write code that sings as well as Solar itself ;-) (a good idea if other people will be reading your code).