How to maintain a design specification in a Scrum environment?

Question

I really like the concept in the agile manifesto that the focus should be on working software rather then on comprehensive documentation. On the other hand a part of my job is also to manage the product and as such I need a up to date version design document at all times. Some might say that the current version of the working software IS all the documentation that I need, but I need the documentation to prove that the product works as per the customers specifications, even after 10 changes to the original design.

In a previous job each and every approved change was integrated in a design document per major feature in the system. This procedure added a significant overhead to each change, since at least one and posible two word docs had to be updated, approved and signed.

At least this procedure worked in a waterfall project but now I am looking for a more agile way to document the current agreed state of the solution so I am really looking forward to hear how you handle this issue, thanks.

Edited: My issue here is how to track how come the system looks or behaves the way it does. So I have an existing system in production and the customers logs an issue that the system should do Y when X is entered. Then I'll need to figure out the current specification for that piece of functionality which might have been changed a number of times in various user stories, sigh.

Answer 1

Your issue tracking system can help to serve the purpose of changes. When you release a new build, you should be able to generate Release Notes from all of the issues that were assigned to that build and closed. This should also organize bugs, new features, etc. You can then incorporate those issues (with description, comments, etc) into your documentation.

Answer 2

G'day,

A design document is essential, but a "complete description of all aspects of a system" type document, created at the beginning of a project, is not a good idea.

You will have to get away from ideas of a design for all aspects of a system that is carved in stone. You do start out with a design and then start breaking that down into user stories which are small concentrated tasks for the parts you will be working on immediately for the first sprint.

Aspects of the design that are being implemented later don't have to be as detailed and in the intial phases may actually consist of many user stories clumped together into a user theme. Even further out, you may have clumps of user themes grouped together into user epics. As the team progresses to later sprints, the user themes are broken down into individual user stories and the user epics may start to be broken down into user themes.

Each sprint may be considered a mini-waterfall project on its own so there will be a requirements gathering and design phase at the beginning of the sprint. This is where the design document is incrementally updated with th e new portions of the design.

This concept is covered in Mike Cohn's "Getting Agile with Scrum" presentation. I'd also recommend his books "User Stories Applied" (sanitised Amazon link) and "Agile Estimating and Planning" (sanitised Amazon link).

BTW If there are many of you new to Scrum I'd suggest getting Mike in to teach one of his courses to you.

BTW Have a read of Martin Fowler's excellent essay "The Almighty Thud" about creating unnecessary documentation.

HTH

cheers,

Answer 3

"up to date version design document at all times"

"My issue here is how to track how come the system looks or behaves the way it does?"

"I'll need to figure out the current specification for that piece of functionality which might have been changed a number of times in various user stories, sigh."

Okay, you've got three separate needs and one document. That will, generally, be a problem.

1. The "to build" doc. What you need to do in the next few sprints. Sometimes called a "detailed design".

2. The "as built" doc. What you did in previous sprints to build the system. This is the usable summary of how the system is.

3. The "to be built" docs. The visionary design that provides a framework into which future sprints can be inserted. Sometimes called an "architectural overview".

You might not want to put all of these into one document.

You might want to have separate documents. You might want to work like this.

1. Write an overview/architecture document. Since you don't know much, this is an overview. A few pages at most. Use a very simple set of tools. We use Restructured Text markup to write simple, plain-text notes.

2. Write a "to build" doc for the upcoming sprints. This is just enough detail to start building. It is not everything; just a few pages. Again, we use RST so that we can trivially manage this with our source code tools.

3. Upgrade the "as built" documentation by folding in the "to build" documents to a more final form.

Answer 4

You asked for, and I quote: "I need the documentation to prove that the product works as per the customers specifications, even after 10 changes to the original design".

In an Agile development environment, the most common solution to this problem, is a suite of Unit Tests. Unit Tests, whether written before the actual development of the software (a.k.a. TFD = Test First Development, or TDD = Test Driven Development) provide you the following:

• The tests are the documentation: The tests are code samples that explain what the individual software components do, and show how to use them.
• The tests also describe the requirements that they fulfill: The top-level component (unit) tests, as well as the integration tests, describe what functionality they support
• The unit tests prove that the product works as per the customer specifications: The tests, with each actual run of the suite prove exactly what requirements are fulfilled and which are not (the tests that fail, and those that aren't there).
• As an aside, non-executable documents (i.e. Word documents, Visio diagrams, etc.) do not(!) prove that the product works as per the customer's specifications - merely show that there is a design for a solution that fulfills the requirements. In fact, the existence of the design document, no matter how detailed it is, does not even prove that the product exists, let alone works as required.
• As long as the tests are ran and maintained, they continue to prove that the software works, no matter how many times they changed. In fact, the when not maintained, the tests often warn that the software isn't in sync with it, because the tests fail.

Long story short, if you want agile development documentation, consider TDD and unit tests.

HTH, Assaf.

Answer 5

Your design specification is replaced by the following

• story cards with acceptance criteria
• automated unit tests
• automated functional test
• automated performance test

The problem with a design specification document is there is no way to verify if it is correct. On the other hand, automated test can be run with every code check in. Not only does it specify what the code does, but it verifies if the code is right. Thus you end up with an enforcement design specification. What design document can make such a claim!

Answer 6

I enjoyed HTH, Assaf. comment: So would you spend $500,000 building your home without specifications? For example, as long as the electricity works I don't care how the house was wired. I can build you a house for $500,000 and I guarantee the water will work, the electricity will work, etc, etc. Just don't ask me how I did it. Does this work for you?

Answer 7

I'm not building a house.

Answer 8

Hey.
Add 'Documentation update' as one of tasks for given feature. You will have to schedule some time for it during sprint planning. Then at all time when some new feature is being released at the end of sprint, you have everything documented, as you did that during the sprint. Just don't fall into to much formalism. Let the developer update documentation for given feature as record what have been done and how it behaves now.
If there is need to go through formal signing and review procedures, you probably want someone else to take developers documentation and integrate it into product specification and have them struggle with signing, reviews etc.