Main menu:

Site search




Specifications: be careful!

Stack of documents One of the things that teams who try agile struggle with is what to do about specifications, from UI designs to feature specs to test plans to software designs. Some agile books leave you with the impression you should avoid written documentation entirely, and it’s true that many teams who practice agile avoid any kind of documentation like the plague. And on the other extreme there are teams who don’t succeed with agile because they burden themselves with too much documentation: they fail to deliver. Most teams are somewhere in between the extremes, but just about everyone asks what to do?

I believe that what matters the most is your mind-set. Here are a few critical elements of the mind-set:

  1. Think minimal documentation, not no documentation. In lean development, any activity that isn’t an end deliverable is a potential waste of effort. One of the reasons many people advocate index cards for project planning for example is that the size is limited. Having a limited space forces us to be concise and to focus on what is most important. I’ve seen many teams move to some form of software for planning and this leads to longer specifications, which unfortunately means they’ve lost a key benefit of agile development!
  2. Remember that the effort that goes into the documentation is always more important than the document itself. I.e. the collaboration through discussions and alignment is where the value is, not in the document. Put hours into discussing a design, not documenting it. I’d rather have 6 hours of discussion in front of a white board over a class diagram and a picture of the white board posted on a wiki page versus 6 hours spent by someone writing a document in some prescribed format any day. The goals of doing a design are good design and alignment that the approach is right.
  3. Always remember that in software development the best way to get feedback from users is through working software, not documentation. Getting users to sign in blood that a spec will meet their needs is going to lead to trouble more often than not.
  4. Remember Alistair Cockburn’s Crystal methods: scale your documentation requirements to the circumstances. The larger your team is and the more distributed it is the more formal you should be about documentation. Too often, small teams will put too much effort into documentation and large teams too little. Small, co-located teams can just turn around and talk. With large teams there needs to be more electronic communication.
  5. Always, always, always look for improvements to your process. Do regular retrospectives as frequently as possible. In my experience, no matter how well things are going there is always room for improvement. Embrace continual change and improvement because when it comes to documentation this is the only way to deal with the question that everyone asks: “how much documentation is enough?”.

Finally, a few quick thoughts on the main sources of documentation: feature specifications (sometimes called feature briefs), UI designs, feature specs, test plans, and software designs.

Feature Specifications

Our natural tendency when negotiating with customers, end users, or end user representatives is to get a complete list of all their requirements, write a specification usually with some design in it, and look for sign-off. This approach might work fine if you’re specifying a building or a renovation project but most software projects are too open-ended with a huge variation in implementation and delivery options. Users will sign a document and more often than not when they get the software say “that isn’t what I needed!”.

Never ask for a complete list of requirements.  Instead, find ways to tease out the core requirements.  For example, google for “Design the box” and “elevator test”. 

If you can get a user to describe what they want in the time it would take to ride an elevator 5 floors you could just have your feature spec.  Great!  Move on and focus on the software as fast as you can and be prepared to iterate outside the core requirements. Agile methods are designed for iteration, transparency, and negotiation. Build an environment where you can trust the development team and the end users to work together and ensure projects are considered done as soon as possible.

Software Design

See point #2 above. Focus on a good design and agreement on the design, not on the document. Talk about design as frequently as you can. Keep a white board reserved for the latest design of your product, ideally if it’s in a place that everyone walks past every day.

UI Design

UI designs are great and very valuable if they’re done right. UI mockups that show a rough form of the UI and markup to show workflows or even a PowerPoint with simple animations can be tested with users and co-workers before any software is written. It’s almost always cheaper to iterate on a UI prototype than it is on UI coded in software. And don’t be afraid to steal good ideas from other applications!

A fun and simple package that we use at work is “Balsamiq Mockups” for UI designs.

A word of caution though: don’t get carried away on the designs. As with feature specs, try to spend the majority of your time on identifying and refining the core workflows. Do the rest in code and try to get to code as fast as you can since that’s where you’ll get the only feedback that counts.

Test Plans

You should always emphasize automated testing over manual testing. Specifying tests for completion for core workflows is fine, especially if it’s done in a brief form such as on the back of an index card. In my experience, if you require enough manual testing that you have to write test plans you’re doing something wrong. Usually, your software isn’t architected for testability. Put more effort into fixing that than into the test plans!


Comment from Peter Quinn
Time January 16, 2010 at 1:59 pm

Hi. I am a long time reader. I wanted to say that I like your blog and the layout.

Peter Quinn

Comment from tattoo designs
Time July 17, 2010 at 8:36 am

Very interesting post. Keep writing dude !!

Comment from przewoz osob do Niemiec
Time July 24, 2010 at 10:45 am

I was bored, until i’ve found your website, interesting posts

Comment from Marybeth Worsell
Time November 8, 2010 at 1:58 pm

This domain seems to get a great deal of visitors. How do you promote it? It gives a nice individual twist on things. I guess having something authentic or substantial to post about is the most important factor.

Comment from Sophia Bush
Time November 16, 2010 at 10:05 am

Nice to be visiting, It has been quite a while one or two things I wanted. Well just use this one, much appreciated. I need it for a project, lucky it is on the same topic as yours. I am relieved that I found it, have a good one.

Write a comment