Hi all,

At the small(ish) company where I work, we have always had a informal approach to all things documentation - especially the tech spec. Now we're getting bigger, and looking at outsourcing, so we're thinking about a more formal "template" for our technical specs to standardise the documents we produce.

We tried it before but it failed on account of a really lousy template. Does anyone here have any feelings on this - is there such thing as a template that covers all technical issues AND aids the developer without bloating the document with lots of vague ambiguous sections...

Matt

Hi Matt,

I use templates all the time. I probably have close to 200 or so for every phase of the development( ie. business requrements, functional specification, feature specification, architecual plan, end-of-life plan, etc). I like using templates as they let the author of a document know what needs to be in the document. In addition, templates allow for standardization of documents. Nothing worse than having two web projects, for example, with two completely different types of functional specifications (sections missing from one that's included in another and vice-versa).

That being said, a template is just a template and it's just a starting point. You have to customize a template for you own specific needs. Every organization/project is different. You tweak templates until the template becomes standard. That's what I used to do, so every new web/windows project has a basic template(in my case a set of templates) which outlines the sections which are required.

s there such thing as a template that covers all technical issues AND aids the developer without bloating the document with lots of vague ambiguous sections...

I doubt this, as I mentioned previously, templates need to be customized according to your needs and every organization/project is different.

[Edit] One thing I forgot to mention is the use of templates is not for everyone. I have found that the larger the organization, the more they want to standardize their internal processes, hence the use of templates. If your a small shop or a single developer, while templates may be beneficial, someone has to manage and update those templates.

I agree with Eric that any document that you produce has to meet your needs. I work for a large organization that is at CMMI Level 4, which means that we produce tons of documentation for every phase of the project. The bad part is that the project management group has tried to create templates to cover all teams which doesn't quite work. We have 200+ developers working on everything from .Net, VB6, C, mainframe, data warehousing, etc. So it is often frustrating dealing with a generic documents with sections that don't quite apply.

I'm not sure how detailed your tech specs need to be, but Joel (from Joel on Software fame) released the technical specs that he had written for this summer's Project Aardvark intern project. It was interesting to see a real example from someone who spends a lot of time talking about doing it right. See http://www.joelonsoftware.com/articles/AardvarkSpec.html for more details.

Thanks for the replies!

I think you have both confirmed my thoughts on this - theres no uber-template that you can download and use, its different company-by-company, and probably even project-by-project.

I'll check out what Joel has published, and see if I can use that as the basis for a template suggestion here.

Thanks again!