Fog Creek Software
Discussion Board

Revising Functional Specs

Since the Functional Spec is a living document how does one best keep track of revisions?  Just adding new stuff and making changes to the existing text seems ineffecient. 

Friday, February 8, 2002

Well, I always did mine in Word with revision marking turned on.  Distributing it on paper with marking turned on for printing showed everyone the sections that changed.

And we checked specs into SourceSafe with the rest of the project code.  That way people could always check out the latest version.


Bob Crosley
Friday, February 8, 2002

The changes have to be recorded somewhere, it may as well be in the FS.

I agree with Bob, we have also kept the various revisions in VSS or CVS or whatever source control you are using.

It does seem inefficient, but it's inefficient to have changes too, nothing is perfect.

Saturday, February 9, 2002

I do like this:

Document version tracking

The version numbering of the document will be a letter followed by a numeric. So, for example, the first release of the document will be A.01 and the second A.02. Any major changes to this document should be realized by incrementing the letter part of the reference. Minor changes are indicated in the numeric part of the reference.

I save the file with the new name, accept all changes in it w/ the changes tracking feature of word and I activate it again for tracking the new changes.

Sunday, February 10, 2002

oh.. and I name my files w/ this A.01, A.02 and so on in the filename too... So I can diff the files.

Sunday, February 10, 2002

I think it is always useful to print a document footer on all specifications including the release number and date. Really rapid development afficinados may want to include the time.

One trap that I have found easy to fall into is to use the "Insert Date" function of the word processor as this results in a new version of your document every time you print.

Peter WA Wood
Sunday, February 10, 2002

When I worked for a NZ branch of a blue chip org, we used two different methods for two different projects.

The first project was huge and didn't so much have a functional spec as a ginourmous database of requirements, use cases, demonstrations, prototypes and marketing literature.

The second was supposed t be a lot smaller. It had a pretty good set of specifications all painfully entered into an AS/400 terminal session!

Once a functional spec was signed off by all parties involved it was supposed to be frozen. This meant only noisy and boisterous managers from outside the team could make changes to the spec.

We coders eventually finished the project, having implemented a set of functionality very different to the one originally agreed. To my knowledge, it's never been used.

Monday, February 11, 2002

I've done the same as other posters here: version the documents with suffixes or use Word's version tracking. Both are ok, but I wish I had something where the history was more clearly part of the document--scroll down to see the old description of the feature. 

Has anyone experimented with a blog-like format for specs? It could easily include user comments, and works chronologically. Each section of the spec would have to be its own blog so that everything on that page was pertinent.

I don't know, I think it could work.

Andrew H Otwell
Wednesday, February 13, 2002

You could version requirements and specifications using something like FogBugz or Bugzilla. 

Simon Lucy
Thursday, February 14, 2002

We used a combination to address two different needs:
- Word's revision marking for formal change tracking
- a small (<50 words) "what's new" for every version we published (with the aim of having a max of 10-20 versions throughout the lifetime of a document) for bringing people up to speed

Monday, February 18, 2002

*  Recent Topics

*  Fog Creek Home