“vague requirements, bad acceptance criteria, good luck!”

yup, this is the same kind of requirements that you get even if you try to nail them down too! (as an example, a 10,000 requirement document that took a government client 4 years to create was still full of inconsistencies, vagueness and even internally contradictory statements. If 4 years of requirements documentation can’t get you a decent, exact, requirement, do you ever think you’ll be able to get anything non-vague?)

So… the agile way was invented to understand that this sh*t happens and to work with it rather than try to work against it.

You start of by asking “what do you want” and the customer replies with “something kinda like this”. You do some work and then go back to the customer and say “is this like what you wanted?”, and the customer usually says “yes but…” whereupon you ask “what do you want”.

Eventually you get exactly what the customer wanted, even if they don’t know what that is! (hell, they never know what they want, not exactly).

On our team, since going agile, we’ve also been trying to narrow down and understand just how much documentation is actually required. I can share with you what we’ve learned up to now.

Before anything else, make sure to read this article on Agile/Lean Documentation. Very good read.

Secondly, I would strongly advise you to reconsider producing design documents after preliminary work on stories. We’ve tried that before and it has proven to be a waste. In the middle of the last release we’ve decided to update the design docs ONLY AFTER the code for the story is delivered. And now I’m thinking even that is too soon.

You need to ask yourself why you want to do design docs prior to coding. For us these were the reasons:

1. We as a team need to understand how the story will affect the design.
2. Having design documents has proven useful when new (or temporary) members join the team or when returning to code that no one has worked on for over a year. So they are useful for organizational memory to help understand how the code works.
3. Design documents are useful for maintenance engineers who may need to troubleshoot the code after the release.

To satisfy (1) you do not need to produce an actual design document. Your team should still have a design phase prior to coding, but that phase can be as simple as a 15 minute session in front of a whiteboard or a napkin. You do not need to produce an actual document that will take hours (if not days) to write just to discuss the design changes.

(2) or (3) are not needed during development of the current story and more than likely they will not be needed for several subsequent iterations.

Also keep in mind that every time a team member is writing/updating design docs, that’s the time that code is not being written. When you write docs before actual code, there is almost 100% chance that they will require to be updated because once you start coding design always ends up being altered. And even if you write design docs after the code, as our team has learned, refactoring from subsequent stories still alters the design.

So what I would recommend:

1. Initially produce temporary designs/models enough so that your team can have an intelligent conversation prior to coding. Do not expect to keep these and do not waste time on formalizing them.
2. Only produce official design documentation if someone will need it (i.e. your team has a real need for organizational memory)
3. Only produce design documentation on code that has been stabilized. There’s no point trying to document a module that keeps being changed in every iteration.
4. Produce design documents which fully describe a module (or portion of the product). In the past we used to write design docs which documented the changes that have to be made. Those docs were completely worthless as soon as the release was done.
5. Keep the document very high-level. If you write 20 pages covering architecture and very high-level design, that document will a) actually be read by other people and b) will help people get familiar with general layout of your code. For details people can go straight into the code. If you write 700 pages of detailed specification, they will almost always not match reality, it is too much for anyone to read and you will end up having to maintain and update 700 pages instead of 20 whenever future changes are made.

The Agile “mantra” is not to do without documentation entirely.

The Agile mantra is to prefer “Working software over comprehensive documentation”. But note the bit at the bottom of the manifesto.

That is, while there is value in the items on the right, we value the items on the left more.”

Uncle Bob has a good policy for documentation

Produce no document unless it’s need is immediate and significant.

You’re right that some people use Agile as an excuse for not producing documentation, but that’s bad Agile. It’s ignoring the bits that I’ve highlighted in the quotes above.

All that said, when you say ‘we currently face a situation where a new feature may impact multiple areas in our “big ball of mud” system’, if you’re going to be Agile, you need to do something about this.

When you have your documentation, use it to modularise your code. That way you remove the long-term need to maintain the documentation (which won’t happen) by removing the long-term need for the documentation.

ie. Make the need immediate and significant.

The thing about agile is that documentation efforts really have to be driven by the scrum team. If the developers don’t feel external documentation is sufficient for their needs, the user story gets blocked until they do. If the business feels developers aren’t producing adequate documentation, the product owner insists on making it part of the acceptance criteria. Because of this, I’ve actually found our documentation to be more focused and effective since moving to scrum.

We use VersionOne to track our user stories, but I’m sure our methods apply to other systems. It lets you attach files to user stories. We have found that to be an extremely useful place to put design documents.

For one example that worked really well for us, we had a need to test a new circuit board design as quickly as possible after the prototype was built. We made two user stories for everything that needed testing: one to design the test and one to execute the test. One acceptance criterion for the design story was that the test procedure was fully documented in the execution story.

When we got to the testing part, it went more smoothly than I’ve ever seen. We just opened the user story and followed the step by step procedure. The documentation was exactly what we needed to complete the story, no more and no less.

We have another story in our backlog just to improve the documentation for a chip we use, in order to make it easier for other teams to pick it up for their own products.

In summary, if you feel your documentation is suffering, the solution is as easy as making a separate user story for it, and/or making it part of the acceptance criteria.

When you speak of poor requirements, the first thing that comes to mind for me is making sure you have the test criteria. If possible create some reusable automated test cases for existing parts of the system. Once everyone becomes comfortable with that then move to writing the test cases before the code is written. Good test cases can do a lot to document the behaviors of a system.

As to what specific design documents to use, as other have already said, it is highly dependent on the needs of the team and what the next task they will be undertaking is. When possible try to use tools that can generate the documents (from code) you would use, or generate the code from the document. Maintenance of documentation can become quite expensive, so choose wisely when you persist a design document.

Personally I have had good success with class diagrams generated from code and fitnesse test cases. The team prints out a couple of the class diagrams, do a mark-up session with the product owner and then formulate an estimate from there. As far as fitnesse goes, I am fortunate to work with a couple of product owners who are very good at expressing what they want in spreadsheets, which are then converted to tables for fitnesse.