Agile Design Documentation: Four Lightweight Alternatives

I recently had a great conversation with Jeff Nielsen and Srini Dhulipala regarding design documentation. Note that we are distinguishing between the intellectual endeavor of “design” and the slightly less intellectual endeavor of “design documentation”.

We all agreed that:

• Future developers will seldom go back and actually read big, detailed documents; they will usually prefer to just have conversations with knowledgeable people and perhaps read a few high-level documents.
• Despite the change, organizations still feel a strong need to have design documentation “just in case,” although it is unclear who the real consumer is for these documents. The point is executives typically demand it and we need to find low-cost ways to provide it.
• The current development team typically doesn’t need design documents. In fact, they typically create them at the last possible minute, often after the code is written, signifying that they didn’t really need the documentation in order to get the coding done.

So given all of the above, we want to create the lightest weight, least obtrusive form of design documentation that still meets the organization’s needs. Here are some of the ideas we discussed:

1. Lightweight Design Templates
2. Recorded Conversations
3. A “3 Questions” Document
4. Whiteboard Capture

Design Templates

Templates are a common solution to the design documentation problem, but leave a bad taste in our mouths because people will just mindlessly fill out the template without putting any real thought into what’s really important.

Suppose, for example, that some piece of functionality has some thorny issues related to transaction handling. If the developer fills out a design template that calls for database structures, UI approach, OO classes, etc., then they may never talk about the transaction handling problem itself because the question is missing from the template. The solution, of course, would be to grow the template to encompass every possible problem, which would be ridiculous.

Later, when a future developer reads a template (assuming they do!), they don’t really know whether the stuff in the template is included because it’s really important to the problem at hand or because the template calls for it. So the templates don’t really do a good job of highlighting the real issues for future developers.

Any really good info is probably buried under a bunch of unimportant stuff that was put there just to satisfy the template and there is no way to know what is really important and what is not.

Recorded Conversations

The real learning for new team members happens during detailed discussions with more senior developers who’ve been on the project for a while. These conversations typically yield a wealth of knowledge regarding pitfalls, compromises, and possible solutions. Recording these conversations would capture what is really important. But we also agreed that with a video recording might lead to less “truth” in the conversation, as the nitty-gritty stuff is addressed later in off-camera conversations.

We also weren’t sure if organizations are ready to accept recordings as valid documentation, because it’s difficult to search and catalog in meaningful ways. Still, recorded conversations do seem like the right general direction.

The Three Questions

Another option is to change to a more open template with only three questions:

1. What, if any, are the potential issues related to these user stories?
2. How did you solve those issues?
3. Why did you choose to solve them that way?

A more open-ended approach opens the door for a wide variety of potential issues to be discussed in meaningful ways, getting us closer to the intellectual meat. What’s the problem? How did you solve it? Why did you choose to do it that way?

And just as important, it allows the writer to leave out stuff that is of no particular concern. However, we’re not sure if most organizations are ready to accept such an open-ended solution.

Whiteboard Capture

The final method we discussed was good old-fashioned whiteboard capture. The team discusses some thorny issues, draws out some plan of attack, captures some constraints, decisions, diagrams, etc. We then take a picture and hopefully, if legible, that photo captures the essence of the problem and the solution.

I like this approach but I have seen many an illegible whiteboard full of scribbling that really would have no meaningful value to anyone who wasn’t part of the original conversation. Still, it captures the fact that the team held design sessions.

Other Ideas?

Let’s set aside the need for design documentation for now. Assuming that someone is demanding it and that you need to produce it, what are some low-impact ways that are working for you?