So why should we write specs? you may be asking.
Why won't people write specs? People claim that it's because they're saving time by skipping the spec-writing phase. They act as if spec-writing was a luxury reserved for NASA space shuttle engineers, or people who work for giant, established insurance companies. Balderdash. First of all, failing to write a spec is the single biggest unnecessary risk you take in a software project. It's as stupid as setting off to cross the Mojave desert with just the clothes on your back, hoping to "wing it." Programmers and software engineers who dive into code without writing a spec tend to think they're cool gunslingers, shooting from the hip. They're not. They are terribly unproductive. They write bad code and produce shoddy software, and they threaten their projects by taking giant risks which are completely uncalled for.
– Joel Spolsky on Painless Functional Specifications
- Specification Template
- Considerations
A sample template for an Specification: https://gist.github.com/pablasso/796a257a7578f2da4ea34ba8503b9b98
A single project may and will contain several specs. If you're feeling like writing an IBM manual from the 80's, that's pretty much the signal that the system, and thus the spec, needs to be broken down in sub-systems.
Diagrams are encouraged where it makes sense. Use the tool of your liking.
ASCII Diagrams
Normal Diagrams
Before implementing them they should be approved by at least one peer.
If the code is not considered not "code complete" and there's design changes, the spec should always reflect that, that's the purpose of the disclaimer section.
If the spec goes out of date then the maintainer is to be blamed. Quoting Joel:
The updating continues as the product is developed and new decisions are made. The spec always reflects our best collective understanding of how the product is going to work. The spec is only frozen when the product is code complete (that is, when all functionality is complete, but there's still testing and debugging work.)
While you're writing a spec, remember your various audiences: programmers, testers, marketing, tech writers, etc. Leave side notes all over the spec whenever is needed. Labeling them as "Technical note", "Marketing note", "Testing note" etc will make sure people can easily browse your document for the notes they're interested.