Specifications – Writing Unambiguous Specifications in Natural Language

I found the Java language spec both formal and readable, and I think it has a sensible structure. Some of the W3C specs could be good examples as well.

Doing the formal work could help you keep language complexity down and see the corner cases.

Headings brain dump: source encoding, lexing, fundamental types, literals, operators, expressions, simple statements, conditionals, loops, functions (definitions and calls), type declarations, modules, compilation units, variable scoping, various kinds of name resolution (eg imports, methods), memory model, side effects, typing, concurrency…

Did you read part 2 of the article or his sample specification? They embody a couple important principles when writing a specification.

• Don't overdesign. The purpose of writing the spec is to force you to think about important things like what happens when there's an error, and how you expect the user to interact with the system. You don't have to go into inordinate detail to get something you can work from. You do need details, though.
• It's about communication. The purpose of the spec is to come to a common agreement about what needs to be done. It's not an ironclad document that requires the force of law. It's a tool to help you better understand your client, and your client to better understand what you want to do for them.

The best advice is to write enough so that you are clear on what you need to do. If you have open questions, document them in the spec and get answers from your client. Once you adequately understand what's needed stop.

If you are not careful, the document will take on a life of its own. It should have one purpose, don't add anything to the document that doesn't fit that purpose. It should be easy to maintain. If you have your entire detailed class diagrams in there along with other details that really belong in a unit test, you will either abandon the document because the upkeep is too much, or you will never get the project completed.

About Writing

Writing for people is hard. In fact, the two hardest things about writing is knowing how to start, and knowing when to stop. In the beginning you just have to do something. My advice for dealing with these two hardest aspects is:

• Know your audience. Who is supposed to read the spec? If it's just you and the client, then that's who you are writing to. If you have someone responsible for testing, you'll have some notes for them as well.
• Start with the highest priority thing. While authentication is important, the login screen is probably the best understood piece most folks have to write. Instead focus on that feature that your users need most. You know, that part that makes them money and is the whole reason they need the software.
• Fill in details as the questions come up and you get answers. Keep things really simple with napkin drawings if necessary until the client is happy with the arrangement. It's important to know what information is involved and how they will use it.
• Stop when adding more doesn't add value. There are some details you just don't want in a spec. You need to know when you have the right thing. You don't need to know that there is a variable inside a method named "albaquerque". That's source code, not specification stuff.