What are some resources for learning to write specifcations?

Question

At work I am responsible for writing specifications quite often and I am also the person who first 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 specification (we are both inexperienced in it) they put in table names and things that I don't think belong etc. So what is a good way to learn to write a good spec?

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

Answer 1

The important thing is to get something written down rather than worry about the format.

Answer 2

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 3

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.

Answer 4

Buy Books: Requirements Engineering by Ian Sommerville & Pete Sawyer ISBN 0-471-97444-7 or Software Requirements by Karl Wiegers ISBN 0-7356-0631-5

Answer 5

See Painless Functional Specs by Joel Spolsky.

Some of the things he says every spec should have:

• A disclaimer
• An author. One author
• Scenarios
• Nongoals
• An Overview
• Details, details, details
• Open Issues
• Side notes