The current status of the spec, i.e "This spec is not complete, is missing x" or "This spec is considered complete".
John Doe <john.doe@example.com>
Someone must take responsability and ownership of the document. Even though everyone is reponsible for updating a spec for anything they change, this person is responsible for the document in case the spec is incorrect.
This is a high level description of the spec. The big picture. Include diagrams if needed.
Things we are not going to do. i.e. "We don't care about performance in this release. The product can be slow, as long as it works. If we have time in version 2, we'll optimize the slow bits."
Here you will fill all the assumptions that you have that you have granted that it will work (later you have to prove that those actually are true).
For example.
- This design will handle at least 10k request per second.
- There's an API that I can use to get this data.
Later you have to prove those with a small prototype, a benchmark or relevant data and update the spec with your finds.
This section is all about the details. Describe with detail how everything in your system will work, down to actual pseudo-code, objects, interfaces, messages, sub-sections, etc. Anything you need to explain your implementation.
If this gets overly long, you may be tackling too many problems at once.
What is this spec missing? What it doesn't solve right now but needs to in order to be complete? This section is good to generate discussion on how to solve them. By the time the programmers start work, all of these need to be stomped out and this section will be empty.
I have created a Google Docs version of this that we can copy and fill out in Google Doc form:
https://drive.google.com/open?id=1jrZ5GcivT7PEd0UpjxjYtAhaC05kSRK4lQ_O8q5Iy_c