December 2013 Archives

I have written many design documents in my day. In most cases, the documented design had only a passing relation to the final implementation and rapidly became a fossil on our wiki. In the best case scenario, the document closely matched the implementation and I took great pains to update it with each iteration upon that codebase. I then left the company, and they promptly ditched my entire solution regardless of the awesome doc. In short, my track record with these documents is not exactly stellar. Regardless, I still think design documents are a good idea for a couple of reasons.

The first, most obvious reason that design documents are helpful is that it's a forcing function for actually thinking deeply about software design. I am not advocating a thousand pages of sequence diagrams here. Simplying laying out the components and their dependencies is helpful: it informs the sequencing of the work, you have to think about the trade-offs involved, and it allows you to form initial ideas on the size and scope of the problem. This sort of documentation won't answer all hard questions about this particular design, but it is helpful in calling out many of these questions.

The second, sneakier yet more important reason that design documents are helpful is that they give you an opportunity to analyze an ambiguous problem and propose an elegant solution. It's hard to do that well, and it turns out this can be important for your career. Think of it this way: if you work in a growing organization, there's a bunch of good code being written. Consequently, if you want to differentiate yourself and ensure great opportunities come your way, it may take more than good code.

There are plenty of ways to differentiate yourself (mentoring, championing best practices, officiating the office ping pong tournament). I'd argue that writing and presenting effectively on software design is one of the rarest and thus one of the best. Additionally, the hardest and most important problems often have an element of design. These problems aren't just distributed randomly. If you want to work on them, it benefits you greatly to have a strong record of proposing designs and seeing them through implementation to delivery.

At this point, I have clearly convinced you (odds of this actually being the case: 48%) and you are firing up your text editor to begin your journey to Documentation City (odds of this actually being the case: 0.48%). How do you get started? My suggestion is to start small, with respect to the size of the document, scope of the problem, and amount of review. As you look at more problems in this way, you'll iterate on your approach and find a style that works well for your team and its problems.

About the Author

The Art of Delightful Software is written by Cody Powell. I'm currently Director of Engineering at TUNE here in Seattle. Before that, I worked on Amazon Video. Before that, I was CTO at Famigo, a venture-funded startup that helped families find and manage mobile content.

Twitter: @codypo
Github: codypo
LinkedIn: codypo's profile
Email: firstname + firstname lastname dot com