(Written originally for Duck Pond Software Blog – December 2011)
Something has been bothering me for a long time. I wrote “Smooth Sailing” a few years ago when I was astonished that people didn’t recognize the value of having good documentation – moreover they thought it wasn’t possible. I’d used DOORs successfully for years and to me, having developers work against a spec, give feedback, collaboratively develop the spec and code together, then have QA test against the spec assured a final spec that matched code that Tech Support could use to know, decisively, how the code was supposed to work.
That let us clearly specify customer complaints as Bugs (don’t match the spec), Enhancement Requests (not in the spec) or “Gaps” (maybe should have been in the spec in the customer’s eyes but were missed. Or spec ambiguities.) That saved us a lot of discussion time in our SDRB (Software Design Review Board) meetings where we reviewed the issue clients and internal support people had with the product. Bugs were things developers missed – the onus was on the Development Managers. “Bad Developers”. Enhancements were things we put in the next major releases. Obviously not negotiable for maintenance releases. Gaps were negotiable but there was no blame on the developers – so yep, good idea, let’s move on it. Meetings were clear. No contention.
So why didn’t everyone want good, ‘as built’ specs?
I was surprised when some companies thought they had ‘as built’ specs – only to find what they were referring to were documents an external tech writer group wrote after the software was released. Those aren’t “as built” specs as much as they are “what we think was built” specs. Since the developers didn’t code to them and QA didn’t test to them in the initial release, they are, always suspect. Those documents are never valid, correct. I would question if any company devotes enough time and money to guarantee that kind of ‘after-the-fact’ documentation is correct.
Whereas it’s so clean and clear if the spec is used as part of the development process and then as part of the QA process that it “IS” the “bible” of the code. How the code was developed. What the code does do. If you have specs like that, you know what’s in the code. Tech Support knows what the product does. Everything is clean. Clear.
But I’ve come to realize that there are roadblocks in companies to why this isn’t as easy as I assumed. But I think I have a solution and am working on it. It’s very cool. I’ve realized that there are real reasons why people feel it’s hard to maintain real as-built DOORS-type specs. I, as a manager, was willing to do the extra work to have as built DOORs specs because I saw the value. But not everyone is as dedicated to the end result.
There has to be a better way.
I think there is. We’re calling it Software 2020 – a software tool for the 21st century “:-)”
Software 2020 Blog 