views:

5288

answers:

8

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

What do you guys use? How in depth do you get while writing the specs? Any additional general tips you could provide would be appreciated.

My company needs these badly. I work for a contractor and right now we do not use these documents at all.

EDIT: I have read Joel's take about Painless Specification, I really liked it, but are their any other opinions :)

+4  A: 

If you want to purchase a book, Software Requirements by Karl Wiegers has templates for a few documents as an appendix. Unfortunately, I'm at work and that particular book is at home. If someone has it handy, they might be able to confirm that.

Thomas Owens
+2  A: 

You can buy templates from ieee and other places, but I have always ended up making my own.

For a technical spec, "Code Complete" by Steve McDonnell has a good checklist, you can draw some info from that. At my last job, I just made a template out of his section headers, and tweaked it from there.

As far as a functional spec, the important thing is to define all the interfaces:

  1. UI (screen mockups)
  2. Software interfaces (plugins, etc.)
  3. Hardware interfaces (if appropriate)
  4. Communications interfaces (Services, email, messaging, etc.)

There should also be a section for business rules, things that are important functionally that are not covered in any interface definition.

Guy Starbuck
+6  A: 

Not a template, but Joel has written a couple of articles on writing a functional spec. He also has sample here.

Galwegian
+2  A: 

I happen to like this one, among others: ReadySet.

He sells a pro version too.

Ben Collins
A: 

Start off simple, and work your way from there. Since this is your first experience working with this, use a word document with bullet points. Write it, re-read it and provide enough detail that it makes sense. For technical specifications, you may want to lead the developer toward a solution, but for functional specifications the "how" should be completely missing.

srclontz
+1  A: 

I would suggest to have a look at the Roberston's Volere template here. They are part of the Atlantic Systems Guild, together with people like Tom DeMarco and Timothy Lister of "Peopleware" fame.

Ralph Rickenbach
+4  A: 

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 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 spec 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 small part of the change you want to make.

Mark Nold
A: 

Came across this template - looks good to me

http://www.cmcrossroads.com/bradapp/docs/sdd.html

RN