Last week I’ve written the WTFM blog, and then Sys-Con decided to reprint it. Apparently, Active MQ guys got offended and left angry feedbacks there. They did not get my message. I have nothing against their software, but if they do care or do not know how to write documentation ABOUT THEIR PRODUCT, I will write about it publicly. They teach me how to get help from the open source vendors. Thank you very much. I was just asking for a short writeup describing how to configure Apache Active MQ with Apache Tomcat…

Most people do not know how to document their creation. They describe the details of their software, but they do not write the BEST PRACTICES MANUAL on WHY AND HOW we should use their software. If you turn the key, the engine will start. If you press this pedal, the car will move. Why won’t you start with the statement that this car has been produced to get you from the point A to point B and the most effective speed is from 50 to 70mph? Or this may not be the case, and this car has been created just to improve your social importance, which means that the make and model matters more than efficiency?

Kathy Sierra is an excellent writer. I’m sure you know her Head First books. Yesterday she’s bloged about her photography classes, and she ran into the same issue: lack of best practices manual. This is what she writes about the photography class she’s attended:

“For most of us, the problem was NOT that we couldn’t learn how to use anything but automatic “P ” mode. The problem was that we didn’t know why or when to use anything else.
It wasn’t simply a camera problem–it was a photography problem. The camera manuals describe precisely how to turn the dials and push the buttons, but never tell us why we’d want to. They focus on the tool rather than the thing the tool enables (taking pictures). What good does it do to master a tool if we haven’t understood (let alone mastered) the thing we’re using the tool for? ”

That’s the major problem of most of the open source vendors. They do not bother explaining WHY and HOW should I use their software in the real world, where people are already using someone else’s software (surprise, surprise!). Pleeease, if you are about to make the world a better place by offering us your tool, sit down and desrcibe the best practices of using it with what the most popular products that we already have. Not just how to use it, but the proper way of using it. If you can’t describe it BEFORE your software is ready, do not even start working on it. Most likely this project will fail.