The value of an updated specification

Question

I'm at the tail end of a large project (around 5 months of my time, > 60,000 lines of code) on which I was the only developer. The specification documents for the project were designed well early on, but as always happens during development, some things have changed. For example:

• Bugs were discovered and fixed in ways that don't correspond well with the spec
• Additional needs were discovered and dealt with
• We found areas where the spec hadn't thought far enough ahead and had to change some implementation
• Etc.

Through all this, the spec was not kept updated, because we were lean on resources (I know that's a questionable excuse). I'm hoping to get the spec updated soon when we have time, but it's a matter of convincing management to spend the effort. I believe it's a good idea, but I need some good reasoning; I can't speak from very much experience because I'm only a year and a half out of school.

So here are my questions:

1. What value is there in keeping an updated spec?
2. How often should the spec be updated? With every change made that might affect it, just at the end of development, or something in between?

EDIT to clarify: this project was internal, so no external client was involved. It's our product.

Answer 1

It depends.

Keeping the spec updated during development has a lot of benefits, including:

• implementers, usability testers, QE, doc, etc. always know where to go for the current agreed-upon design
• outside observers (e.g. managers or stakeholders) can see what you're intending to do
• the team has something to look back at to figure out if things changed during implementation. Obviously this requires a version-controlled spec.
• most importantly, it forces you to write down things. The process of writing things down reveals a lot of hidden assumptions.

But not every change needs to be reflected in the spec. Just like what level of detail to put in the spec in the first place, some things are just too minor. This is a judgment call, and the team will have to settle on a practice here.

Updating the spec is also extra work, of course, and so it's important to make sure that extra work is adding value. If you find yourself routinely updating the spec with no one using the result, then that's a warning flag (and might mean changing your team practices rather than holding off on spec updates).

The longer the project, the more important it is to update the spec. One hour feature? Probably can get away with just implementing it. One week? Update that spec from time to time. One month? Definitely worth it to check in repeatedly.

Finally, the larger the team, the more valuable it is to have a written spec. BUT--larger teams have a harder time of maintaining context, so the spec might not be able to stand allone: it might get misinterpreted by folks who don't understand what it all means. So it's only one piece of the puzzle.

Answer 2

I believe the most important thing that an "as-implemented" spec should cover is the reasons for the decisions that you made. Everything else should be obvious from the code and the tests (I hope half of those 60K LOC are tests!). In other words, the "what" and "how" are already expressed in the code, which is the most up-to-date "document" that exists.

People who read your code later (including you) will wonder "why" you did things a certain way and that's not something the code or tests can answer. Questions from the low-level "why did you use a LinkedList instead of an ArrayList" to the high-level "why did you use framework X instead of Y or Z?" are important to discuss in an document that's written after you've implemented things in code. There's nothing worse than encountering some code that does things a certain way, changing it to some other mechanism, and finding out your new way doesn't work and then finding out that your "new" way had already been tried and discarded! If only someone had told you...

As for how often should it be updated, my rule-of-thumb is whenever a non-trivial decision is made. If you wait until you've finished a feature, or portion of a feature, you'll probably forget some of the nuances that went into your decision to do things a certain way.

Answer 3

Let's start with the process by which you estimate how long it takes to do your work. Always estimate time for documentation and meetings and email communications. Now for future projects you won't run out of time to do those things. Also assume only 6 hours per day per person when figuring out the end date for delivery (there is always indirect work such as required HR meetings and vacation, etc. to account for, you can never plan for anyone to be on a project 40 hours a week or you will miss every deadline and never have time to do documentation). These are the two most common reasons why I have seen people run out of time.

To my mind what is critical for you to update on this last project are the bugs you fixed that did not meet the spec. Personally your manager failed there as he should never have allowed that to happen, particularly if the customers (and internal users are also customers) were not informed beforehand. There may be a good reason from a user perspective for that requirement that you threw out because it was easier to fix the bug if you ignored the requirement. They may now be expecting behavior they are not going to get. That is a failure of your entire development staff that you allow such actions to happen.

One reason this needs updating is for maintenance. Sooner or later someone new will come along to fix something that was changed without documentation and will think that the failure to follow the spec was a bug, not a deliberate action and will change it back to follow the spec.

Or the users will complain that it doesn't do X which was in the spec and you won't have any proof that X was changed because Y bug caused X to be reevaluated as a requirement. Having been in a few of these argumnents in the past, I can tell you they aren't pretty whether they are internal or external customers. The less agreement you got for these changes before you did them, the more likely they are to rise up and bite your development staff later. And six months from now you won't remember why you did it that way either. It's no fun to explain why you did something when you have no idea why you did it.

Additional features aren't as critical, but should probably at least be listed even if you don't have the time to do a complete description.

You need to make these changes now when they are fresh. Convince your manager to let you spend a day or even half a day doing this. Or sneak in a half-hour every day for the next couple of weeks if you have to in order to document the most critical deviations.

Answer 4

Bugs were discovered and fixed in ways that don't correspond well with the spec

Additional needs were discovered and dealt with

We found areas where the spec hadn't thought far enough ahead and had to change some implementation

All of these cases should have sparked an RFI (Request for Information) back to the consultant/client - and no work should have been done until an amended specification was returned.

What value is there in keeping an updated spec?

How often should the spec be updated? With every change made that might affect it, just at the end of development, or something in between?

Covering your backside

If the changes were made to the software without any such amendment to the spec, then when you deliver the project you are now open to the client pointing and saying "this project isn't within specification" (this has happened on at least one project I've been on - thankfully, we had the RFIs and change documents to argue the point). You have to have the paper trail to support your change.

Having a clear change process helps in other ways - one project (not software) I was involved with had the client complain when their system was broken. We actually pulled out the specification, and the (several) documented RFIs which showed clearly that we considered the specification to need amendment, and the responses from the client saying 'just do it like we said'. The client ended up having to pay for the original project, and then a second project to patch up the original problems (suffice to say, they didn't ignore RFIs the second time round).

Changes to Costs

There's one last advantage to reviewing and updating the specification continuously - some changes will incur a major time impact on the development. This means that there may be an additional cost to bear by the client (which was the motivation for the above-mentioned client ignoring the RFIs). Since the original project timeline and price was based on the original spec - running through a change process will ensure that the client is aware of increases in time and price needed for various changes.

Answer 5

Just a legal aspect: Never.

When the spec is part of a contract, you should never change the spec. I would add notes, addendum, or change document or something similar.

At the end you may define a revised spec. The customer should give the ok during the acceptance procedure.