Templates of Technical and Functional Specs [close

问题:

So basically 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? 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 there any other opinions :)

回答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.

回答2:

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

回答3:

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.

回答4:

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.

回答5:

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

He sells a pro version too.

回答6:

This is the best one I have found: http://www.jiludwig.com/templates/FRDTemplate.doc

回答7:

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.

回答8:

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.

As the template is copyrighted, I will not reproduce it here, but give you some of the main headers:

1. The Purpose of the Project
2. The Stakeholders
3. Mandated Constraints
4. Naming Conventions and Terminology
5. Relevant Facts and Assumptions
6. The Scope of the Work
7. Business Data Model and Data Dictionary
8. The Scope of the Product
9. Functional Requirements
10. Look and Feels Requirements ...

There are many more, but this should give you an idea. The most interesting part of the template is the requirements shell that lists functional requirements on a kind of cue card. Again copyrighted, but truly valuable.

Look here in chapter 9.