Painless Functional Specifications – Part 4 - Tips
Specs are good, but not if nobody reads them. As a spec-writer, you have to trick people into reading your stuff.
Rules to be a good writer
- Be Funny
- Yep, rule number one in tricking people into reading your spec is to make the experience enjoyable.
- Just be careful on where should you be funny, it shouldn’t be everywhere
- Writing a spec is like writing code for a brain to execute
- Instead of writing code for the compiler to read, write it for a logical brain to read.
- Include technical notes or side notes for specifications.
- Humans don’t want to decode something to understand it they just want to read it.
- Write as simple as possible
- Don’t make your readers feel stupid, make sure they know what the key words you used mean so they feel like they understand.
- When writing ask yourself if the person reading this sentence will understand it at a deep level?
- Use simple language and stay away from formal language
- Break things down to short sentences.
- Avoid walls of text, people get scared of a paper full of text.
- Use numbered or bulleted lists, pictures, charts, tables, and lots of whitespace
- Review and reread several time
- If you can’t understand your specs after reading it make sure to rewrite it in a simpler way.
- Templates considered harmful
- It’s not important that every spec look the same.
- Don’t use glossary ideas should be simplified.
- Templates scares people away from writing.