Submitted by InfoWorld’s Tom Yager speaks in favor of the RTFM approach to learning new skills, arguing that the knowledge gleaned from cracking a manual only in search of a specific answer is eroding software quality. “The reason is that developers don’t allow themselves the time to look things up before they use them. Statement completion, context-sensitive help, generated code, unit testing, and automated analysis came about expressly to eliminate research and experimentation from the development cycle. The result, I think, speaks for itself. How many rookie coding blunders that lead to security vulnerabilities grow out of inadequately understood usage of a method or resource?”
Reading the manual requires time. As a general rule, we can say training is needed.
I’m a pretty good programmer and I don’t like to use function/libraries that I don’t understand, but I can’t say I’ve never done something I wasn’t sure about , ran a quick test to see if it works, and then said…okay…let’s move on.
Rather than RTM, I think people need to slow done, value experience, and provide training. Fairly simple stuff, but it’s not done.
People assume programming is programming… which it is. Don’t worry, you don’t have to teach anyone about for loops again and again in different languages. yet, the domain level knowledge, overall software structure, custom libraries… all need proper training. I’m not sure what came first, high attrition rates causing companies to throw people into the fire, or was it throwing people into the fire that led to high attrition rates. I don’t know.
When I was growing up, we had a great manual for the TRS-80 Color Computer. It taught you how to program in BASIC with a lot of great examples. These days you’re lucky if the manual even documents the software properly.
How many people would learn easily from reading the scanf man page that it has been the source of a number of security breaks? How would one learn from reading the average introductory text on programming? There’s probably a way, but I only learned about it by reading forums like this one.
Companies learned a long time ago that they could save boatloads of money by skimping on the manual, or by selling them in bookstores, or (worse) by charging developers hundreds of dollars in addition to the software, just to see a manual. All too often the manual either isn’t there, or is hard to find, or is poorly written, or doesn’t cover all the ins and outs of the features, or even (all too often) is out of date and/or flat-out wrong.
Documentation is a lost art. Sure, one problem is client laziness, but another problem is supplier miserliness. There’s a chicken-and-egg argument here.
What manual? The one you first placed into the garbage can where you also put your installation media and accessory cables.
You need to divide between computers for home use and those for professional use when you’re refering to the time of the TRS-80. Home computers usually came with basic (not neccessarily BASIC) manuals, and there were additional books you could buy. Professional computers came with a shelf of ringbooks or folders. Imagine the documentation of an IBM mainframe.
That’s the funny fhing about those problems: You don’t know then until they cause big trouble.
Programming is learning by doing.
Programming?
Interesting, that’s what companies do – entities that usually have lots of money (but, as you explained, they want to keep from spending).
For example, the FreeBSD project is one of the most excellent documented pieces of software – especially interesting for programmers. Every system binary, system file, maintenance procedure, library call, driver and kernel interface is documented well, simply enter “man” and the thing you want to know something about. Furthermore, the system’s source code is very tidy, uses functional identifiers (where you can tell from their name what they are used for) and explainatory comments. And now for the surprise: You can get this for free! And is has been created by people that usually don’t have tons of money to handle.
Sad statement, but surely true.
Well said.
“unit testing, and automated analysis came about expressly to eliminate research and experimentation from the development cycle.”
What unmitigated rubbish…
So the author prefers non electronic manuals. Big deal.
when i need to resort to the manual it’s because of bad software. this is most of the time because of inconsistent command line arguments. if the unix command line tools have a real standard for command line arguments my manual reading will drop significantly and my productivity will go up.
for anybody writing a manual, please do not only explain how to use it but also why it is made that way. most likely during this process you come up with a lot of improvements.
Although it’s left up to the individual programmer, some pseudo-standards have emerged, which can be found in ESR’s The Art of Unix Programming ( http://www.faqs.org/docs/artu/ch10s05.html#id2948149 ). For an overall “manual” to get to know some best practices and common pitfalls of Unix programming, I thought this book was a great starting point.