At my workplace, we face a challenge in that "agile" too often has meant "vague requirements, bad acceptance criteria, good luck!" We're trying to address that, as a general improvement effort.

So, as part of that, I am proposing that we generate design documents that, above and beyond the user story level, accurately reflect the outcome of preliminary investigations of the effect of a given feature within the system and including answers to questions that we have asked the business.

Is there an effective standard for this?

We currently face a situation where a new feature may impact multiple areas in our "big ball of mud" system, and estimates are starting to climb due to this technical debt. Hopefully more thoughtful design processes can help.

  • 4
    agile's solution to this is communication. People responsible for knowing WHAT should be always accessible to developers for consultations. Also, you should have unit tests and frequent refactoring to keep the "big ball of mud" in check.
    – Euphoric
    Aug 29, 2012 at 11:41
  • 4
    I know that we should have those things. We don't. I'm trying to help us get there, and I'm trying to institute a reliable, repeatable framework for communications (documents are communication, after all). Problem is, right now we get into heavy "get it done now!" cycles, and we rely on ad hoc communication that results in people having knowledge silos because there is no reference for the real information about a feature that arises after the user story.
    – asthasr
    Aug 29, 2012 at 11:45
  • 4
    Agile is not against documentation - it is against useless documentation. Write as much documentation as you need, and no more. Specifically, keep in mind that documentation is only a reference to the mental model you (the team) have in your heads. The latter is the really important stuff - however, you can't fully document it ever. Instead, keep it synchronized via lots of communication, and write down only enough references to it to ensure that the model is kept consistent in the long term. Aug 29, 2012 at 11:52
  • I think you should ask different question than this. For this kind of question, you will get generic "documents are OK when ..", that wont help you much. You should aks if your solution to your problem is right and ask about other possible solutions.
    – Euphoric
    Aug 29, 2012 at 12:01
  • 4
    "Agile is not against documentation - it is against useless documentation.": Every development process is against useless documentation (according to their definition of useful and useless).
    – Giorgio
    Aug 22, 2013 at 7:24

5 Answers 5


"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).

  • That government design document anecdote is interesting, is there a source? Or just something you experienced firsthand?
    – user145400
    Apr 13, 2015 at 22:18
  • Is a downside of this that the customer doesn't really know what they want. Or they want something very specific and you have multiple customers so you need to 'refactor' the ideas from multiple customers into a single coherent design that works for 'everyone'? Dec 13, 2020 at 6:07
  • @MattCochrane the customer always knows what they want, its just that they have difficulty describing it effectively, and definitely not to such an extent that they can describe it as comprehensively as they try to do. Agile often takes an opposing view - of starting vague and working back (this is just as bad IMHO), but there is a sweet spot of a initial spec that is more broad in its requirements, and gets refined over time. As this is what happens anyway, even with the proscriptive requirements approach.
    – gbjbaanb
    Dec 13, 2020 at 15:31

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.
  • What you're saying seems similar to what I'm trying to arrive at; we have a complex ball of mud, and I want simple documents that a) communicate the business intent of a particular feature (i.e. elaborated user stories, with questions answered); b) point out which portions of the code and existing APIs will be affected; and c) are treated as one-time artifacts, not something that has to be updated with every new feature, forever. Saying 20 pages is "high level" is interesting to me -- we're devoid even of that. :)
    – asthasr
    Aug 30, 2012 at 4:01
  • @syrion: Based on what you just said, it sounds like you want to document in detail every single story and produce a "design gap" document (i.e. define the difference between what's in the code today and what will be in the code once the story is done). Do you have an audience for such documents? From my experience, I'm predicting no one will actually read them. Developers working on the story today already know what needs to change (their either wrote the document or were part of initial discussion). And if you try to capture ALL details of changes you are about to make for a story,...
    – DXM
    Aug 30, 2012 at 4:16
  • ... you will spend more time writing documentation than actually coding. And once the story is done, like you said these are one-time artifacts. So why do you need to produce them in the first place?
    – DXM
    Aug 30, 2012 at 4:16
  • because at the moment we have an environment rife with knowledge silos. We have people who know subsystem A because they wrote it, and B because they helped support it when it last exploded, but never touched C and D has been rewritten since. It is difficult for newbies and off-site contractors to get into or stay in the loop.
    – asthasr
    Aug 30, 2012 at 4:24
  • @syrion: it really sounds like you have same need that we have. However, I'm puzzled when you said you want simple documents that ... treated as one-time artifacts. So let's say you have a layer that talks to the DB and 6 stories that require changes to that layer. Are you planning to produce 6 different documents along with each story? Or do you want to have one single design specification for the DB layer? However, single specification is something that will have to be updated with every feature that touches the DB layer.
    – DXM
    Aug 30, 2012 at 4:34

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.

  • This answer is "correct", but doesn't really think beyond that. What about an architecture design for example? What about developer/business turnover? How is this handled by lots of quality unit tests?
    – Paul
    Aug 29, 2012 at 14:10
  • @Paul: It is a good idea to have VERY high-level architecture diagrams, along with very light-weight coding standards, for new-comers. I've found that a good way to keep those documents up-to-date is to keep them in a wiki and get each newcomer to update where they find it is dated. But this question was about up-front design documents specifically.
    – pdr
    Aug 29, 2012 at 14:31
  • I still stand by what I'm saying. Change Architecture to whatever the business wants to call it, and change unit tests to regression tests (automated?) and it applies.
    – Paul
    Aug 29, 2012 at 17:03
  • @Paul: Sorry, I'm not following. What worthwhile document do you think I'm suggesting is bad?
    – pdr
    Aug 29, 2012 at 19:59

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.