A Word About Manuals

In this day of frameworks and new languages with new paradigms and new strategies to increasing developer efficiency the modern programmer has to do a lot of thinking on their feet. As programmers/developers we are gift with the quite thinking highly analytical mind necessary for our profession and our personal success; in most cases. However, even the most skilled programmers must consult a reference for their tasks, whether it be learning or using, a manual is something the modern programmer is coming to expect, in some form or another.

Now a manual is not always obvious, nor does it have to be. When I program in Visual C# .NET I have been able to figure out how entire sections of the framework work by simply reading the intellisense documentation put together by Microsoft. However, this is a rare case, as most programming languages do not have an IDE that supports such highly sophisticated features. Some would say the IDE does not need it and the programmer should be charged with this task. That is, however, a separate argument and not what I am discussing in this post.

What I am curious of is why most new programmers do not use the manual at first. Being an active member on IRC Freenode, in particular in the #php channel, I have had the chance to see many of the problems plaguing people new to the PHP world. It really surprises me how mundane some of the questions are. Things like, “how do I use this function?”, “how do I add elements to an array?”, or “how do I work with multi dimensional arrays?” etc. Such questions are easily answerable by the PHP Manual, which is, IMO, one of the best programming language manuals on the Internet. It is so good, that I consider the need for a formal book on PHP unnecessary.

However, that said, having such a good manual is not always a good thing. As in the case with PHP this leads to people programming, who maybe should not program. Now, I am not one to discriminate, but based on some of the questions I have been asked, and I only named a few, I seriously wonder about some of the people who are programming out there. I hope it is only inexperience with programming that is the result of such questions, or not being use to such a good reference being available.

Now, look at Ruby on Rails manual which is, if your not an experienced programmer, horrible. A lot of the people I have talk to in the Rails community agree with this and agree that the manual needs a lot of work, namely the addition of examples. We often joke that the manual serves as a deterrent to discourage inadequate programmers from picking up such a beautiful piece of art that is Rails. Truly, Rails is not for the faint hearted, its not so much difficult as it is unconventional for the untrained (or uneducated) programmer. Its rules can seem like a limitation when really they are the keys to the shackles, like .NET was for the Windows programmers. But I am not going to turn this rant in a Rails praise article, their are enough of those by the fan boys already.

What I am trying to point out is that even in the case of a good manual people often over look it and ask questions that shouldn’t be asked. Yes, its nice to ask someone and get the answer quick, but I often wonder about the amount of effort expended to find the answer. I know their have been times that I have served as a walking encyclopedia in the PHP chat rooms, this is not my function, nor why I hang around in the channel. PHP has a great manual, and it should be utilized to the fullest extent. This is true with all manuals. I had a case today where I had a question about a new tool I am playing with called CakePHP. My answer was not in the docs, but rather was something obscure that had to be answered by one of the developers. But before I asked the question I sifted through the manual and made sure I couldnt find the answer there.

So next time you have a question about PHP, .NET, Java check the Manual/KnowledgeBase/API, if its about Rails, well check the manual still, but keep your IRC app on standby. And don’t forget Google, the programmers best friend 🙂


Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s