You might think I’m obsessed with having good specs and system documentation. I’ve blogged about it enough. I’d answer that it’s not an “obsession” but that it just makes good business sense. Even stronger than that – I do not think most software companies can operate effectively without on-line access to the final requirements specification.

I’m not referring to User Guides or System Administration Guides that can written by tech writers after the software is complete by using the software itself. I’m talking about the specs that capture the business requirements behind what the code does including all of the possible business variations and configurations that needed to be coded for. That documentation is very tough to write after-the-fact, especially if the code is complex and has a lot of parameters, switches and properties to support different customer configurations and business uses.

Why do we want it?

Why would we want to end up with accurate requirements/design documents? I asked some key individuals if they thought that requirements management was important. They all worked in a company used to having an on-line requirements management system integrated with their mainline software development process resulting in clean, accurate on-line requirements specifications. Their comments:

• [Development Manager]: Our specs are absolutely fabulous for requirements tracking and as a reference/knowledge-base. For the entire company. It is a must for any software company…
• [Developer]: I think it’s critical to have documented what the software is to do so the developer knows what to do and the QA team knows what to test. Having accountability is huge.
• [Call Center Manager]: Without documented specs, only the developers can support the software – that’s not efficient.

Why doesn’t everyone have it?

Why don’t all companies have good up-to-date on-line specifications?

• It can take a lot of time and effort to keep specs up-to-date
• Particularly if the spec is written at the start of the project, as the product evolves or changes occur (as they always do), the spec becomes out-of-date.
• Inaccurate specs are just a pile of words – worthless.

Because of the above issues/difficulties creating and maintaining good documentation, most Agile proponents advocate doing away with specs. I think that’s “throwing out the baby with the bath water!”

We developed Software 2020 to fill this void, solve this need. Before Software 2020 we did it with DOORs Requirements Management System and our internal SD Tracker plus a lot of manual effort and manual linkages. But it was worth it even then.

What Makes a “Good Spec”? Accuracy!

I’m convinced that to maintain good, up-to-date, accurate specs, producing specs must be part of the process. Developers need to use them while they code. The specs need to be on-line and able to evolve as changes occur from the product owner or from feedback by the developers. They need to be tested for accuracy as part of the QA test process. Every new change needs a link to the coding task that will implement it.

Good specs are living, breathing documents. Good specs are part of the software process, where the entire team takes ownership and responsibility for their accuracy. That doesn’t mean that there is added work, rather that when used for reference (by anyone – the call center, developers, testers) if the code doesn’t match the spec, a task is created to resolve that mismatch.

In an Agile environment, why can’t Specs be part of the DoD?

If specs are just part of the Definition of Done (DoD), two scenarios are possible:

1. The become inaccurate over time because they are not used during code development, changes aren’t tied to specific code tasks, and aren’t part of the test plan.
2. ELSE the process could require the Product Owner to add all final changes/updates to the existing specs, the developers to review all changes and QA to verify as part of the DoD. However, this will end up being a significant added cost and I contend that this kind of after-the-fact effort will not result in as accurate or complete a spec as a process where specs are used during coding and during test as part of the process.

Related Blogs

• March 2012 – Where do you go to see what the code really does besides asking a developer?
• March 2012 – Who Needs Documentation?
• July 2012 – Automatic Documentation – How we use Software 2020 to build Software 2020
• And in August 2012 – Lessons from the Moon – Gotta Have Good Documentation