Reading through Christoph’s take on Joel’s latest “How to be a Program Manager“, I stumbled across the term “Functional spec”.
Coming from a C.S. background (admittedly, a sin of my youth), I continue to struggle with the term “specification”, as I associate it with
- using a formal language, e.g. predicate logic
- formal verification of programs
- defining the complete input, output and behaviour of the software using these tools.
I don’t think you can fully understand the problem domain, the software to be written and it’s interaction with users or other systems by creating a text document in plain English (or any natural language of your choice) deliberately sprinkled with some graphics – of course you can’t do it with predicate logic either.
The main reason is that while creating your “specification” you will lack the feedback you get from actually implementing the system and from putting your code in front of users. This is way more valuable than sitting in an ivory tower waxing eloquently about a system’s intended features.
So I suggest to put another label on the document Joel is talking about – “Functional Overview”, “Functional Description” or “Functional Outline”. Don’t burden a useful document and its intended purpose with putting an inappropriate and misleading label on it.
Now that we this issue out of our way, we can start having a more useful discussion about what to put in the “Functional spec”, err, “Functional Overview”. Here’s my take on it:
Here’s what we know now. This is what we have to be aware of when starting out. This is how the interaction with the user might work out. Here are the external dependencies on other systems.
Just write enough “Functional Overview” that you are confident in your ability to move through the problem domain and take turns as you learn new things implementing the system and putting it in from of customers. You will be way better off investing your energy in defining the expected inputs & outputs of the system (and its components) as automated functional, acceptance and unit tests. And getting the system out to users & testers in order to get real feedback of a real system and learn about the shortcomings of your initial specification.
There. I said it.