Aug 29, 2010

Agile Value #2: Keep Documentation Light

Let's look at the next core agile value.
We value working software over comprehensive documentation
No amount of system documentation can compensate for a non-existing system. We can spend the better part of a projects life time writing specifications, discussing use cases and drawing designs charts without actually producing anything truly valuable for our customer. Working software is always more valuable than documentation and that is always the way we measure progress.

Not all documentation is bad, just that most of it is not really needed, and it is tedious to keep in sync with the actual software. Also, when documentation and implementation does not agree -- who is right?


The classic requirements document is created through sweat, tears and lots of frustration. Frustration because it is a document predicting the future. If we predict the future wrong (which we will), it will inevitably cost us money, trust and maybe our jobs. Nothing good can come from this. 

Instead, things planned for the future should not be detailed at all and stuff that is nearer should be fleshed out more completely. When it is time to implement them, we should spend more time detailing them. This is the moment when we have as much information as possible, but not before that. This is called the latest responsible moment.

One way to think about it, is to imagine that you have all planned features laid out in front of you, from your feet towards the horizon. Items that are closer to you is more important right now and are seen clearly with details and everything. Things further away are a little blurred and only the title and some text is readable. Things even further away are so blurred that it is not possible to make out any details except the headline. When the nearest items have been implemented and the next features are shifted towards you, you can see them more clearly and you notice they are lacking crucial information. Now is the time to add more details.

Systems Documentation

Scrum and XP is based on the core agile values which is about preferring collaboration and working software before documentation and tools. It means that your time is best spent creating a shared understanding of the system design rather than writing detailed documentation. For this to happen, the team must talk about the design all the time; how to make the design better and how to adapt it to new changes. Constantly. All members in the team must be involved in the design discussions. Here are a few pointers:
  • Don't write any systems documentation unless you have working code. Defer any such efforts until you have delivered your first incremental release. And as always, keep it simple!
  • Draw an outline of the system so the team can easily to see how different parts are connected. This is the overview and should be pretty stable over time. Keep it up prominently on a wall.
  • Locate your most important entity in your system (Order, Blog Entry, Transaction, ...) and create a state diagram for it. I have noticed that having the team create a few state diagrams helps their understanding of the system and they may even find a few quirks or bugs. Once the system starts growing, add one or two sequence diagrams showing a typical "request" through the system.
  • Readable code without comments is what we are aiming for. It is much better to write clean code than copious amounts of documentation.
  • I recommend adapting a mentality that considers every comment in the code as a personal challenge: Can I rewrite and clarify the code so the comment is not needed anymore?
  • Use refactoring techniques with unit tests and don't be afraid to use longish function and variable names to make things clear.
I am going to write more about comments in a later post, so I'll leave that for now.


  1. Decongestants lower this swelling on the mucus walls. When you use most of these, sinus congestion is lowered, improving the best way to clearer sinus passages. These kinds of easily accessible passageways will then more readily get rid of undesirable mucus and infectious contaminants from the nose parts, ultimately causing clean and disinfected nose cavities.Kyäni

  2. Apartments throughout Alanya stay fairly cheep, inside spite involving service fees growing significantly. whilst your current market has been affected from recent financial events, It\'s proved to be able to become much more robust compared to in several different countries. because the new laws came in to The strain allowing foreigners in order to buy land, both necessitate AND charges have increased. Prices, particularly along your coast, are rising rapidly, AS WELL AS are necessary to progress for you to do and so with the subsequently five for you to seven years.It doesn't need to utilize an estate agent to find AS WELL AS buy an Apartment inside Alanya. However, several buyers Choose for you to do, consequently Just as estate agents cater on the specific Specifications connected with foreigners AND are generally aware connected with all the legal requirements. before committing in order to procuring an Apartment, you need to check whether You can find almost any outstanding debts to the property. lägenhet i Alanya

  3. i never know the use of adobe shadow until i saw this post. thank you for this! this is very helpful.

  4. I think that thanks for the valuabe information and insights you have so provided here. pendant lights

  5. An exceptionally complex method for composing, making impacts particularly in dialect and writing.
    software development company in delhi

  6. The main story line features soldiers of delta media player Squad fight to save the humans of planet Sera from a ruthless cavernous enemy, Locust Horde. Players assume the character of Marcus Fenix. Marcus Fenix is a former prisoner and war-hardened soldier.

  7. Hi, I find reading this article a joy. It is extremely helpful and interesting and very much looking forward to reading more of your work.. how-safe-are-christmas-laser-lights

  8. I am working on research I found that the design in Scrum model are not implemented. Can you provide me a proper reference where they are emphasis on design in Scrum Model.

  9. Your business operations keep your company running and generating revenue, so they're necessary. But you don't need to be the one who manages them. If you have a multiple 6-figure+ business and find yourself creating and maintaining systems, establishing guidelines and deadlines for your team, handling product and service delivery, you're stuck in the "DOING" of the business.

  10. Thanks for a very interesting blog. What else may I get that kind of info written in such a perfect approach? I’ve a undertaking that I am simply now operating on, and I have been at the look out for such info. Adobe creative cloud

  11. Finding a decent SEO advertiser isn't simple. With over 3 years of experience and a huge number of glad clients, blog comments service in 1$

  12. This is a great inspiring article.I am pretty much pleased with your good work.You put really very helpful information...Agile Working

  13. Have you ever considered about including a little bit more than just your articles? I mean, what you say is important and all. However think of if you added some great visuals or video clips to give your posts more, “pop”! Your content is excellent but with images and videos, this website could undeniably be one of the very best in its niche. Fantastic blog! where to buy coreldraw


What are your comments? I'd love to hear 'em, so don't be shy now :-)  If you want to get in touch with me directly just drop me a mail.