We recently received the following question:
“I work for a small subsidiary. Can you recommend sources of documentation templates so I can build best practice to model for our parent company? Then I could recommend VisibleThread to propagate the standards.”
The question opens up the very interesting, highly subjective and contentious topic of software process and the ‘best’ document template. I thought I’d share an extract of my answer as it may be of some help to folks considering this whole area. Not a simple question, but here was my answer. A number of questions have a bearing on what type of documentation you use in the lifecycle. I like to consider these things:
- Size, duration and distributed nature of projects?
Larger projects require more controls, distributed projects also require more controls. Long duration projects also require more controls. (i.e. gates in your process and associated templates) - Size of projects, are these projects you work on mission critical or not, or a mix?
The former require heavy oversight, whilst they can be ‘agile’ in very sophisticated organizations, they typically are waterfall if you look closely. Less mission critical projects require way less docs and can be far more flexible in the depth of content captured. - Style of projects, are these projects you work on waterfall in nature or iterative (or agile)?
In reality, many organizations claiming to be iterative/agile tend to be ‘fakes’ when you dig to any extent under the covers, in other words whilst they may have that tag they will turn out to be waterfall. Either way, both approaches require change and need to be measured for change over time in terms of document content - Culture of your organization, is your org open to adopting better practices, are they able to absorb change quickly?
If your org culture is somewhat resistant, I would recommend getting some kind of buy in from management & gradually introduce revised templates over a period of say 2-4 months, addressing certain key areas initially, eg: get a decent func reqs spec in place along with an associated non-funcs spec template in place is always an excellent start.
Regarding templates here a few sources to get you going:
1.) A requirements template I always recommend is James and Suzanne Robertson’s Volere. This used to be a free download, although I see James and Suzanne are now charging a nominal fee. Worth it however as it is very strong and covers out a wide set of considerations in requirements analysis.
2.) Another good option is to search docstoc (or scribd) for templates. Here’s one that I like (and this ships as a sample set in VisibleThread) for non-functionals: [Editor NOTE – no longer available, original link not resolving]
3.) There is an open source project at. It attempts to compile and assemble a fairly complete collection of templates for the various states of the software lifecycle. Whilst it is an interesting project it comes out of academia and is very light on the early stages of articulating requirements but better on later stage docs. Worth a look but I would be inclined to cherry pick and augment with better sources.
We tend to base our guidance on using VisibleThread as the way to help power your approach. VisibleThread does come with a number of very good Best Practices out of the box (based on our own experience and on service partners practices) but in fact any Best Practice template can be used and applied in VisibleThread within 5 minutes to form the basis of any quality and process improvement initiative.
