Tracking changes to a (functional) design document

Question

Hi,

I am looking for a good way to keep a design document up to date with the latest decisions.

We are a small team (two developers, game designer, graphic designer, project manager, sales guy). Most of our projects last a couple of months. At the start of the project a design is made but we generally find ourselves making changes or new decisions throughout the project. Most of these changes are improvements, so we want to keep our process like that. (If the changed design results in more time needed this is generally taken care of, so that part is ok)

However, at the moment we have no nice way of capturing the changes to the initial design document and this results in the initial design quickly being abandoned as a source while coding. This is of course a waste of effort.

Currently our documents are openoffice/word, and the best way to track changes in those documents will probably be adding a changelist to the top of the document and making the changes in the text in parrallel -- not really an option I'd think as ideal.

I've looked at requirements management software, but that looks way to specialized. The documents could be stored in subversion but I think that is a bit too low level to give insight in the changes.

Does anyone know a good way to track changes like these and keep the design document a valuable resource throughout the project?

EDIT: At the moment we mostly rely on changes to the original design being put in the bugtracker, that way they are at least somewhere.

EDIT: Related questions

- http://stackoverflow.com/questions/29810

Answer 1

I've found a wiki with revision logging works well as a step-up from Word documents, provided the number of users is relatively small. Finding one that makes it easy to make quick edits is helpful in ensuring it's kept up to date.

Answer 2

I don't know any good, free configuration management tools, but why not place your design under source control? Just add it to SVN, CVS, or whatever you are using. This is good because:

1) It is always up to date (if you check it in, of course)

2) It is centralized

3) You can keep track of changes by using the built-in compare feature, available in almost any source control system

It may not be the 'enterprisish' solution you'd want, but you are a small team of developers anyway, so for that situation, it is more than perfect.

EDIT: I see now that you already mentioned a source control system, my mistake. Still, I think it should work well.

Answer 3

Use Google Docs. Its free, web based, muti-user in real time, you can choose who has access to your documents, and keeps versioning. You can also upload all your word documents and it will transform them for you. For more information: http://www.google.com/google-d-s/intl/en/tour2.html

Answer 4

Both openoffice and word include capaiblities for showing/hiding edits to your document. Assuming there's resistance to changing, then that's your best option - either that or export to text and put it into any source control software.\

Alternatively, maintain a separate (diffable using the appropriate tool) document for change-description text, and save archive versions at appropriate points in time.

Answer 5

This problem has been a long standing issue in our programming shop too. The funny thing is that programmers tend to look at this from the wrong optimization angle: "keep everything in one place". In my opinion, you have two main issues:

• The changes' descriptions must be easy to read ("So what's new?")
• The process should be optimized for writing of the specification to agree upon, and then get to work already!

Imagine how this problem is solved in another environment: government law making. The lawbook is not rewritten with "track changes" turned on every time the government adds another law, or changes one...

The best way is to never touch a released document. Don't stuff everything into the same file, you'll get the:

• dreaded version history table
• eternal status "draft",
• scattered inconsistencies,
• horribly rushed sentences, and
• foul smelling blend of authors' styles

Instead, release an addendum, describing only the changes in detail, and possibly replacing full paragraphs/pages of the original.

With the size of our project, this can never work, can it?

In my biggest project so far, I released one base spec, and 5 consecutive addenda. Each of around 5 pages. Worked like a charm!