Dont Read Manuals

Problem: Management has given you a task to do which involves something you don't quite understand.

Context: There is a PissingContest happening creating an environment in which acknowledging lack of understanding is tantamount to emasculating oneself right there in the office.

Solution: Guess. Or play ChineseWhispers. Rather than go read a manual to find out if a library function does something, assume it does that. Don't you dare go read the manpage to see what the formatting characters for sscanf() are, ask your neighbour. He'll probably be wrong, but at least you've now absolved yourself of blame for being wrong.

Resulting Context: Lack of good practice anywhere in the organization for anyone to follow. Incorrect knowledge will propagate across the company. Companies which use this tend to like vi as an editor because it's "easy to learn". People don't get given a book on UNIX when they start, they get given a photocopied crib sheet of UNIX commands. People will get confused when an actual Guru turns up and uses parameters to commands they don't recognize. Or whole new commands that aren't on the crib sheet. People won't automate tasks because they don't realize tasks can be automated... people who can write regular expressions possess godhood because it represents magical knowledge...

Known uses: Cynically speaking - everywhere men outnumber women in a software development environment.

Personally, I thought it was hysterical to arrive and be given one place's guide to UNIX. It fitted, including an intro to VI, Make and some shell commands on one side of A4.

A perfect example is a place that uses purify. Or is supposed to: it's been deemed "broken" because some code that runs "perfectly" outside purify breaks when run inside it. Interestingly, this behaviour is in the manual, and it says it's usually caused by uninitialized data being read. After some long amount of time of word-of-mouth rumouring that "purify doesn't work with this class of problems, we don't know why", it was discovered that 1) no-one had ever read the manual pages and 2) there was some uninitialized memory being read.

I've not quite understood the post-rationalization that must happen. Certainly, the thing about people who can write regular expressions possessing godhood is interesting - where do these people imagine I gained that knowledge? Do they really imagine that some people in the world are blessed, and some are not? Or is that I, having the knowledge my profession requires, am a nerd?

I mean, the latter is like imagining that truck drivers who don't have a licence and no lessons but sort of learnt to drive a truck by trial-and-error are more heroic. I can almost see it: they'd say things like "Why are there 6 gears? I only need 1st for slow things and 6th for fast things.." and they'd not bother connecting up the rear indicator lights because they can't see any difference from not putting the plug in.

The former is even worse - imagining that some people in the world can be truck drivers. They arrived in the world with the knowledge and no-one else can ever get it.

-- KatieLucas

My wife gets the same attitude in regard to her ability to illustrate. Some people are just too hard-headed to think someone actually learned how to draw and wasn't given it by mystical infusions through the Collegiate Moon Goddess Of Dawn's Early Awakening manifest in the form of a simple piece of paper with funny words on it.

So apparently, the man command was not on the crib sheet?

Unfortunately it may well be; many people will then think to themselves, I know how to use help, but I never use it.

Also the tip use your wit and intelligence to find things out, thru research and experiment doesn't work either.

This is certainly not isolated to software development. When I reported to work at IBM as a newly hired BSEE in mainframe logic design, I received a lot of verbal instruction, a couple of CLIST files I could tailor (mainframe equivalent of shell scripts) and a list of experts upon whom I could call. One of these latter proudly told me how he had invented a way to model the logic so that he could test its function before committing it to silicon.

A few months later, my team lead told me the office busybodies had noticed that I had not taken the online study courses required for newly hired design engineers. He apologized for the upcoming waste of my time, and told me how to bypass a lot of it. I like to read the fine print on contracts, so I actually read the course material. It was based on printed manuals, which I ordered and read. I was blown away. Here was concise description of the language we used to design logic (it is a programming language in its own right - you compile to silicon, in essence). It turns out that one of the results of processing a design is a logical model of the function - and there is another language that can be used to exercise that model.

Another piece of folklore was about manufacturing testability. For those who don't know, each and every chip must be fully tested, due to variations in the physical processes used to produce them. These tests do not exercise the function at all - they verify that every gate input can be set to both logical states and that every gate reacts correctly to its inputs. One of the analysis programs we would run would measure the testability of a design. It might find some gates whose inputs could not be set to one logical state or the other, or whose output states could not be observed. The conventional wisdom was to shuffle the design around a bit, and maybe devote a couple of the very precious I/O pads to allow the testing machine to exercise/observe those gates. If this sounds like trying to design a test for unreachable code, you're right! Once I understood what the procedure was doing, and what it was trying to tell me about my design, I was able to remove logic and increase the testability. I had been told that 97 percent was acceptable for chips and 95 percent for modules (several chips mounted in one package). Following what was practically a cookbook, I got to 100 percent for both, every time.

The sad thing about IBM is that it has a wealth of knowledge that is readily accessible - and is ignored throughout the corporation. I assume that some departments actually use it, and of course somebody writes it, but based on the several locations where I worked, I would have to estimate it is a small percentage. I left the company eight years ago, and my contacts with IBM technical personnel since that time show that nothing has changed.

Scott Hightower