What are some resources for learning to write specifications?

Question

At work I am responsible for writing specifications quite often and I am also the person who insisted on getting specifications in the first place. The problem is I am unsure how specifications should look and what they should contain. A lot of the time when my boss is writing the specifications (we are both inexperienced in it) they put in table names and things that I don't think belong there. So what is a good way to learn to write a good spec?

EDIT: Should a functional spec include things like assuming I am specifying a web application, the input types (a textbox, dropdown list, etc)?

Answer 1

The most important part of development documentation in my opinion, is having the correct person do it.

• Requirements Docs - Users + Business Analyst
• Functional Spec - Business Analyst + developer
• Technical Spec (how the functionality will actually be implemented) - Sr. Developer / Architect
• Time estimates for scheduling purposes - The specific developer assigned to the task

Having anyone besides the Sr. Developer / Architect define table structures / interfaces etc. is an exercise in futility - as the more experienced developer will generally throw most of it out.

Wikipedia is actually a good start for the Functional Spec, which seems similar to your Spec - http://en.wikipedia.org/wiki/Functional_specification.

Answer 2

There's a great chapter in Steve McConnell's Code Complete that runs through specification documents and what they should contain.

When I was tasked to build an Architecture and Business Analysis team at a company that had never had either, I used McConnell's spec chapter to create the outline for the Technical Specification document. It evolved over time, but by starting out with this framework I made sure we didn't miss anything and it turned out to be surprisingly usable.

When writing specs, a rule of thumb I follow is to try to have technical documents always start from the general and move to the specific -- always restate the business problem(s) or goal(s) that the technical solution is being developed to solve, so the person reading the spec doesn't need to go to other documents to put it in any sort of context.