How do I write a Technical Specification document for my software project?

Question

I've seen a few questions around here saying that there's no need to write a beefy Technical Specification if the Functional Specification has all of the functionality. What about situations where the client has provided a Functional Specification and you need to turn around a Technical Specification from that document?

I understand that within a company writing smaller Technical Specifications focussed on specific parts of the solution is useful but if production of the Technical Specification is a project milestone/deliverable with client visibility what is the best way to approach writing one?

What if I don't know how exactly how I am going to implement a certain piece of functionality because I've not created it before? How can you write the Technical Specification in a way which this played down as not a catastrophe?

I am looking for templates/guidance/best practice suggestions and any real world experience that can help me create the kind of document that can be used for future projects of this nature.

Answer 1

Joel has written about this on his blog:

• Painless Functional Specifications - Part 1: Why Bother?
• Painless Functional Specifications - Part 2: What's a Spec?
• Painless Functional Specifications - Part 3: But... How?
• Painless Functional Specifications - Part 4: Tips

Answer 2

You should start with a sketchy overall design of the solution. You probably know more thank you think about the definitive architecture. For example: do you need a database? an application server? web services? desktop client? clusters?

Then you start fleshing out the components and start asking yourself some basic questions according to the technologies you think are the most appropriate according to the domain of the problem and your knowledge. For example: Java or .NET? Django or Ruby-on-Rails? JBoss or Tomcat? Mongrel or Apache? Oracle or MySQL?

Then you go in for the details. You are still not implementing anything, this is just a preliminary document, and it is very likely that you will change your mind halfway through development anyway. Ask yourself if you are going to need an ORM, a framework, a library, a dedicated device. For example: (N)Hibernate or Toplink? Spring? JSF? Struts? Handheld device? Barcode readers? Don't put any of these in the technical specification unless it forces you to change something (i.e. incompatibility issues).

Now it's time to review everything again.

Search the web for alternatives, newest releases of any component, similar projects, open source competitors.

Add details, correct errors, research the informations for the components you've been vague about.

Ask your colleagues to proof read your document.

Don't put down useless details, try to address the big scale problems, not the tiny optimizations. Focus on what you know best. Create a spike solution whenever you feel like it.

Every time you do a review you'd better compare the architecture sketch against the requirements (don't forget the non-functional requirements).

Make it an iterative process, so that you may improve it and still have a deliverable ready any time for peer reviews and collaboration. Also, if the customer is satisfied with the detail level you achieved you'd better stop so you might concentrate on the development phase.

Answer 3

1. Define the project goals
2. Define the system architecture/infrastructure
3. Define the user dialogs and the control flow
4. Define the background tasks
5. Define the database model
6. Define the interfaces to other systems
7. Define the non functional requirements (response times, security, ...)
8. Define a dictionary for all relevant concepts/entities (dangerous, you may omit this one)

Don't be too specific about system internals.