http://www.joelonsoftware.com/articles/fog0000000033.html

The biggest complaint you'll hear from teams that do write specs is that "nobody reads them." When nobody reads specs, the people who write them tend to get a little bit cynical.

The fact that the spec was shelved (unread and unloved) when it was completed makes people feel like it was all a bunch of work for naught.

So. Specs are good, but not if nobody reads them. As a spec-writer, you have to trick people into reading your stuff, and you should also probably make an effort not to cause any already-too-small brains to leak out through eye-sockets.

Tricking people into reading your stuff is usually just a matter of good writing. But it's not fair of me to just say "be a good writer" and leave it at that. Here are four easy rules that you absolutely must follow to make specs that get read.

Rule 1: Be Funny Yep, rule number one in tricking people into reading your spec is to make the experience enjoyable. Don't tell me you weren't born funny, I don't buy it. Everybody has funny ideas all the time, they just self-censor them because they think that it's "unprofessional." Feh. Sometimes you have to break the rules.

When you're writing a spec, an easy place to be funny is in the examples. Every time you need to tell a story about how a feature works, instead of saying:

• The user types Ctrl+N to create a new Employee table and starts entering the names of the employees.

write something like:

• Miss Piggy, poking at the keyboard with a eyeliner stick because her chubby little fingers are too fat to press individual keys, types Ctrl+N to create a new Boyfriend table and types in the single record "Kermit."

• One of the easiest ways to be funny is to be specific when it's not called for.
  
  Rule 2: Writing a spec is like writing code for a brain to execute
• Humans won't understand what you're talking about unless you motivate it first.
  
• Humans don't want to have to decode something, they just want to read it in order and understand it.
• For humans, you have to provide the big picture and then fill in the details.
• A human brain understands things much better if you can paint a vivid picture in their mind by telling a story, even if it's just a fragment of a story, because our brains have evolved to understand stories.

If you show a chess board, in the middle of a real game of chess, to an experienced chess player for even a second or two, they will instantly be able to memorize the position of every piece. But if you move around a couple of pieces in nonsensical ways that couldn't happen in normal play (for example, put some pawns on the first row, or put both black bishops on black squares), it becomes much, much harder for them to memorize the board.

 The way the human brain works is not random access; pathways tend to be strengthened in our brains and some things are just easier to understand than other things because they are more common.

So, when you're writing a spec, try to imagine the person you are addressing it to, and try to imagine what you're asking them to understand at every step. Sentence by sentence, ask yourself if the person reading this sentence will understand it at a deep level, in the context of what you've already told them.

Rule 3: Write as simply as possibl

Don't use stilted, formal language because you think it's unprofessional to write in simple sentences. Use the simplest language you can.

In fact I think that many people think that clear writing means that something is wrong.

Break things down to short sentences. If you're having trouble writing a sentence clearly, break it into two or three shorter sentences.

Avoid walls of text: entire pages with just text. People get scared and don't read them.

Use numbered or bulleted lists, pictures, charts, tables, and lots of whitespace so that the reading "looks" fluffier.             

Nothing improves a spec more than lots and lots of screenshots. A picture can be worth a thousand words.

Rule 4: Review and reread several times

Um, well, I was originally planning to have a lengthy exegesis of this rule here, but this rule is just too simple and obvious. Review and reread your spec several times, OK? When you find a sentence that isn't super easy to understand, rewrite it.

R ule 5: Templates considered harmful

Avoid the temptation to make a standard template for specs. At first you might just think that it's important that "every spec look the same." Hint: it's not.

Worse, if you have templates, what tends to happen is that you add a bunch of sections to the template for things that you think are important for every feature.

A spec is a document that you want people to read. In that way, it is no different than an essay in The New Yorker or a college paper. Have you ever heard of a professor passing out templates for students to write their college papers? Have you ever read two good essays that could be fit into a template? Just drop the idea.