Question

I am looking for good templates for writing both technical and functional specs on a project or work request.

What do you use? How deep do you get while writing the specs? What general tips should I be aware of?

My company needs these badly. Currently we do not use these documents at all.

Edit

I have read Joel’s take about Painless Specification, I really liked it, but are there any other opinions?

Answer 1

On general tips;

We are implementing a process of

1) Business Requirements Statement (BRS)

2) Functional Specification

3) Technical specification

The BRS covers what the business problems are, and what the requirements are around solutions, testing, security, reliability and delivery. This defines what would make a successful solution.

The functional spec details what is needed, how it should look, how long fields should be, etc.

The technical spec details where the data comes from, any tricky code that may need to be considered.

The customer owns the requirements. The developers own the tech specs, and the functional spec is a middle ground. Testing is done against the tech specs (usually unit testing) then against the functional specs (usually system testing) and then against the requirements (UAT).

The important part of this (and we are struggling with) is that the developers still need to deliver to the functional spec, and the original business requirements. In reality the functional and tech specs are just there for clarity.

In short, my main tip is to first work out the process you wish to implement. Then seek agreement from all parties involved in your proposed process, then work on the templates to fit. The templates themselves are only are a small part of the change you want to make.