Fog Creek Software
Discussion Board

Handling specs on long term.

If you have ever written specs, you will know that unlike code, a change can go in as an Appendix for easy tracking.

In my project, the number of Appendixes is getting out of control. We are running at Appendix H and all.

Any idea, how to manage the situation  ??

Eldo Daniel
Friday, December 21, 2001

How about revision control of the document in exactly the same way it's done in your code?

In other words, use CVS or something, on plaintext documents (maybe in a wiki style or docbook or something). This way you get to use existing tools , and your problem's solved.

This is basically the solution I ended up using: I extended the in-house task mgmt/ticket system into a project management tool with online docs support. I elected to use a minimalist wiki-style formatting ability , and a basic web editing interface. It works well enough, since requirements docs are generally just text anyway.

If you're using Word and want to stick with it, I think it has a built-in revision system, or at least can keep track of the most recent set of changes.

Steve Willer
Friday, December 21, 2001

Does Wiki have version control? I think being able to see the spec's revision history would be important.

k0d3 p03t
Friday, December 21, 2001

I am a Wiki newbie.  But if you visit [ ], you would notice that this wiki is basically a CVS system at its core.

At [ ], recent changes are visible, and you can look at diffs as well as complete revision history.

October Kent
Saturday, December 22, 2001

What's the format of a spec? Text, or UML or what?

Christopher Wells
Sunday, December 23, 2001

Word has some good version control built in.

Ged Byrne
Friday, December 28, 2001

I struggling with same issue. So far i've come up with the following solution:

I include the name of the project in the document, e.g. DesignSpec_WebService_Tiger.doc (i write in Word and link from Swiki to them). This document is subject to changes for the current project. When a new project starts, i will start a new document with another postfix.

At the start of the document a table with the version information is listed. (These versions are independent of the project/product versions.)

I use the appendixes for design decisions (alternative solutions, trade-off discussions). Otherwise the document becomes unreadable because of all the details. Next, you don't want to read over and over again why something was decided a couple of months ago.

It is not perfect, but suffices (for now).

Friday, December 28, 2001

*  Recent Topics

*  Fog Creek Home