Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
3  
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 '12 at 11:41
2  
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. –  syrion Aug 29 '12 at 11:45
3  
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. –  Péter Török Aug 29 '12 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 '12 at 12:01
2  
"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 '13 at 7:24
show 3 more comments

5 Answers

up vote 7 down vote accepted

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

share|improve this answer
add comment

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.
share|improve this answer
    
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. :) –  syrion Aug 30 '12 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 '12 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 '12 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. –  syrion Aug 30 '12 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 '12 at 4:34
show 2 more comments

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.

share|improve this answer
    
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 '12 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 '12 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 '12 at 17:03
    
@Paul: Sorry, I'm not following. What worthwhile document do you think I'm suggesting is bad? –  pdr Aug 29 '12 at 19:59
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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