Twitter GitHub Facebook Instagram

Daniel Irvine on building software

System design documentation, the lazy way

13 June 2012

I can teach you to write truly awesome agile documentation and still be lazy at it.

Actually, there’s nothing new here. It’s just plain old common sense, although I don’t often see it put into practice. In an agile team a great deal of responsibility is put on developers to be continually producing good documentation of two forms:

  1. story analysis and design proposal, in other words the bit of work when you go away and figure something out, then write it down in order to communicate your ideas with the rest of your team. Sometimes you won’t write this out, but you’ll have to communicate this design with your peers at some point (assuming they are interested).
  2. system design documentation, a larger set of documentation that describes in detail how the system operates, and why it works that way.
We can actually use the same chunk of text for both sets of documentation. The process works like this:
  1. When you start analysis on a new feature or user story, write out the minimum amount of prose that describes what you’re about to implement. Don’t detail obvious design decisions but only those that have required some heavy thinking. Make sure you write in the present tense, i.e. ‘The system does X because‘ not ‘The system should do X because’. Why we do this will become obvious a bit further on.
  2. Re-read and cut it down even further - remember, conciseness is key. Bullet points can be useful here.
  3. Send it out to your team for comment (or just discuss it face-to-face).
  4. Make any necessary changes to your document.
  5. Remove any parts of your document that you now feel are unimportant or that were ‘too obvious’ for comment from your team. This part is quite hard but important!
  6. Repeat 1-5 until you have agreement on the feature you’re about to implement.
  7. Implement in whatever way you see fit (test driven hopefully ;)).
  8. Open up the system design documentation for the area you’ve been working in, or create a new document if there is no documentation for the area you’ve just been working in. (This assumes you’ve got your system documentation organised in a functional way, which you should do. Wikis are great for this sort of documentation.)
  9. Merge in your analysis docs. This shouldn’t be difficult if you wrote your text in present tense. If you’ve used bullet points, fill those out so that they read as normal prose. You should be striving for textbook quality which means the document has to read well from start to finish.
  10. Throw away the analysis doc.
The important step here is step 9, the merge. If you’ve written your analysis doc well, you probably won’t be writing much more. Instead what you’ll be doing is re-reading the existing documentation and adding in sentences you’ve already written and deleting sentences that no longer make sense (and you  should be happy to delete just as much as you add).

Some agile methodologists will tell you that you shouldn’t write any documentation until the feature is implemented. Well I think that unless you’re the perfect programmer, you’re going to slack off on the writing as soon as your implementation is done. You’ll be itching to move on to the next task. So do the writing up front and you’ll only have a quick documentation job to do at the very end of your implementation.

About the author

Daniel Irvine is a software craftsman at 8th Light, based in London. These days he prefers to code in Clojure and Ruby, despite having been a C++ and C# developer for the majority of his career.

For a longer bio please see To contact Daniel, send a tweet to @d_ir or use the comments section below.

Twitter GitHub Facebook Instagram