Joel Spolsky wonders:
Why does every technical manual and book include a section at the beginning on “conventions used in this document,” full of ridiculous and useless tips like, “Tips are indicated by a lightbulb icon in the margin”? Is it because you’re paid by the word?
We aren’t (paid by the word) and we don’t (begin our docs that way). Go free software!
Well, it’s not pay-by-word, but at least a few of the documents I’ve written have that section in them. Why? Well, I put them in because they were in the templates I based my docs on. Everybody else has them right after the legal mumbo-jumbo and before the introduction to the product described.
It’s a case of the “Space shuttle wingspan maxed out at N feet because the tunnels it had to travel through were only Y feet wide, because they used to be train tunnels, whose width was defined by train tracks, whose width was defined by horsecarts, whose width was defined by the width of the average horse’s butt” story.
Perhaps I’m just lucky then that the templates I started with didn’t have that stuff, else I’d be stuck with them too, along with the 4 ft. 8-1/2 in. rails.