Please don't follow Joel's advice. He's taking the wrong lesson. You can be conversational, you can lade your document with copious real world examples and jus

Please don't follow Joel's advice. He's taking the wrong lesson. You can be conversational, you can lade your document with copious real world examples and justifications for rules, and illustrations, and explaining how different parts of the spec interact, and warn about common mistakes and included FAQs, but don't fill it with distracting unfunny garbage like Miss Piggy poking at a keyboard with eyeliner because her fingers are too fat.