Have you ever been totally immersed in a culture where the language is totally different than yours and you’ve had to learn it on the job?
My buddy Nik, from Russia, came to America and had to learn English as he was starting a job to be a kayak guide…a job that is 90% communication. I know some of my co-workers were getting frustrated with the communication gap, but this guy learned English, in my opinion, at an amazing rate & was able to communicate with co-workers and customers pretty darn well in the first 3 weeks.
So, here I am, 3 weeks into Zend Framework, a PHP Framework, and I feel like pulling my hair out. PHP is a language that helps computers talk to servers, and the best way to explain a Framework is to relate frameworks to dialects. In the south, we use y’all, ain’t & a’ight to package multi-word phrases into single words. Frameworks are the same way. Someone takes the original language and packages it to make it easier to use.
Here’s my real rub with creators of frameworks (and dialects for that matter): There’s rarely a Codex (or in depth guide on how to use them) and the ones that exist make a lot of assumptions, and don’t help users get to the core of working with them.
When I jumped into WordPress, which is a Framework of PHP, there was SO much to learn, but it’s documented so well, that you find yourself getting deeper and deeper into the framework because you want to.
I’ve found that the Zend Framework documentation leaves out variables that should be declared, leaves out some semi-colons (which as a programmer you should know to use) and doesn’t comment out the code it’s sharing.
It’s like my friend Nik coming to the US, me telling him to say, “Give water”, when he really wants to say, “Can you please give me some water?” and expecting him to be able to say it to a waitress at a restaurant without the waitress getting totally insulted.
Where’s the user-experience? The end user is who ANYTHING you produce a framework, product or website for, so why, as a developer, would you make it SO stinking hard for someone who understands the “native” language to use your framework?
So there it is. If you’re creating a framework, working on code that someone else is going to have to work with later, or expect to have to bring someone up to speed on a project you’re working on, make sure you comment out your code, create detailed documentation or give a Codex under the assumption that the people using it have never worked with a framework or at least, have never worked with your framework.
What do you think: Is it important to make sure documentation is accurate, detailed and robust?

People don’t say it so we’ll focus on the content, but because we’re so easily drawn by first impressions (the cover). We constantly make assessments based on first encounters (what you see, hear or smell…that’s right, I said smell).




Open an image you want to work with and grab a single toned, white vector of your logo. If you don’t have a logo, or don’t have it as a vector, it’s okay, just type your name in white and place it over the top of your image.

