So the title was meant to catch your attention and I hope that it did. Seriously, if you would like to see several examples of specifications that Microsoft development teams are using to develop the next version of Visual Studio (code named ‘Orcas’) and Team Foundation Server, check out the following link:
The teams are releasing these specifications in order to get feedback from the community about how some of the new features in the products will be implemented. This is your opportunity to look at not only the content of the specifications, but the format of the specifications and to apply them to the specifications that you use within your organization (you do have a spec, right?). Here are some of the things that I took note of when I was checking out these specs:
- They are using the proper tools to create specifications. Lists of items captured in Excel Spreadsheets or Tasks in a Microsoft Project Plan are not specifications. I am speaking from personal experience and I can show you scars from this one.
- The specifications are written down. Oral specifications do not count, they are too subject to modification and interpretation (again I can show you the scars on this one).
- There is not one mega-specification, but rather lots of little specifications (one per feature as a matter of fact). The notion that you need to have one huge specification was created to sell 3″ D-ring binders.
- Every one of these specifications can be absorbed and understood in less than 1/2 an hour. I looked at about 1/3 of these specifications and I did not see one of them over 12 pages (title pages and legal disclaimers aside).
- All of these specifications followed a consistent format. After I had read a couple of them the following ones all seemed familiar. Even when a section did not apply, it was still there (I saw a couple blank no-goal sections).
- They made liberal use of screen shots and other visual aids, such as state diagrams. The quote “a picture is worth a 1000 words” is as true in spec writing as it is in photography.
- Several of the specifications made use of scenarios or story telling. It is a lot easier to understand what to implement if you know how people will use the system. “After sifting through some documentation, Mort realizes there is a Script Explorer window. He turns it on and finds that it lists all the client-side documents that IE knows about. He finds the script block he was looking for and is now able to set breakpoints.” Very easy to understand.
- Issues are highlighted with easy to identify font formatting – they jump right out at you and they are inline in the document, not kept in a separate issues or open items section. When they are resolved, they are
struck outnot removed from the document.