Fog Creek Software
Discussion Board

Documents (specs, ...) : how do you manage them ?


Hard to explain my quesiton in a simple "subject" field...

I regularly work on specs, "schedule of conditions", ...
So I start with the goals, the way we want to reach them...
Then, after a while, the upper management decide to change something that makes 50% of my document obsolete.
For example : I'm working on a project which require the intervention of an external company... We chose it and start planning the intervention. So in my docs, I start to explain how we will make this intervention,...
Suddenly, the upper management says "hum this company is not reliable, this one is better" ...  but this other company has totaly different manners to do the work.

So what do I do ? Do i start a new chapter in my document saying "the company x seems to be bad, so whe chose y instead" ... and explain the new "way  of intervention" ?
So I keep traces of the whole process (the first choice, why finally it wasn't a good idea, the second choice...)

I find it's a good idea, but my docs quickly become heavy and filled with 80% of "out dated" information... I'm not sure if my manager and the other people involved in the project find this usefull...

On the other way, it's simple to delete the out dated parts just to keep the useful ones... but at the end of a 6 months project (6 months because of contant changes) I would end up with a tiny 10 pages document... not really in balance with the project's duration.

So what do you do ? what do you recommend ?

Olivier B
Monday, August 9, 2004

Use a document control system which enables you to revert to earlier drafts.

Or, if you haven't got the budget, give your document a version number and include a History Section, e.g.:

Version 1: Initial draft
Version 2: Section on rubber hoses removed as feature judged not economical.
Version 3: Changed to reflect new supplier for kevlar chaucibles (Starry Wisdom Ltd)

A short final spec is a Good Thing, since a spec is a working document which has to be used,

Air Condo Victim
Monday, August 9, 2004

You might want to keep the history in a seperate file, a projrct log or something, so that you can check out the changes and their effects when you need to. But 95% of people reading a spec don't really care about the historical reasoning, they just want to know how to code something, so the shorter doc is good.
Nobody likes to read a long spec, so they'll thumb through it and you'll end up with a product that matches the few paragraphs they did read in the spec.

Different audiences need different documents.

John Q Tester
Monday, August 9, 2004

Hells bells lad, history is littered with final position statements and this is your opportunity to add one more to the heap. Do your manager a favour and track his current thinking without too many footnotes. Do your system implementors the same honour if you don't want to be  best guest at a lynching.

If you want to CYA or retain notes for your autobiography / historical novel / letter to the paper / diary then version the stuff. Just don't pass it downstream. They'll hate you.

Most of us bottom feeders aren't interested in your preceding cosmic battles, we've troubles of our own, hopefully but not entirely distanced from  "schedule of conditions" which I must now google.  "heads of agreement" check. "Glossary" check. "terms of reference" check ...

Monday, August 9, 2004

You can either archive the file into source control (in which case you should use a text file format such as RTF or HTML), or use the versioning feature that comes with Word or similar word processor (but I don't know how reliable that is.)

Either way, the changes are available for those interested... and invisible for the others who couldn't care less.

Monday, August 9, 2004

watch out for that Microsoft Word document versioning... Microsoft has a history of circulating documents in which the previous version had some err... not so politically correct stuff in it.

Monday, August 9, 2004

Use Sharepoint WSS (free, not the portal server, which is NOT free) and enable document versioning.  Works great and the price is right.  In addition, WSS has some other features that make team development easier (do not confuse w/ teamware, not THAT much easie, but easier ... tasks, lists, etc.)

Monday, August 9, 2004

All my Word specs and Visio diagrams get checked into CVS. It does a great job of tracking old versions, and I can restore to any if I need to.

James U-S
Monday, August 9, 2004

*  Recent Topics

*  Fog Creek Home