Design Documents Part 2 (Benefits of Writing Design Documents)

Philip O’Tooles articles on design documents (dd) provide a lot of information about writing a dd and what should be in and out of a dd. One thing I want to mention are the key benefits of writing dd (some of these were covered by Philip) but I have a very strong view that the full benefits are not always understood. Here’s my top 3:

  • Avoid design mistakes
  • Better Test Cases
  • Helping new hires

Avoiding design mistakes

To me this is the best reason for writing dd’s. It’s all about peer review. You show what you are building to your peers, manager and architects (if needed). You catch things early. You avoid stupid mistakes, database design problems, using wrong patterns,using wrong frameworks etc… etc… because you asking your community for a review. Key to this working is keeping the dd small. As I say again and again: “there is nothing like a one pager” or even just a photo of a whiteboard session.

For larger systems, projects, features I involve a large group of individuals including: Architects,DBA’s, Developers, Testers, Security, Dev Ops/Operations and Wizards*.

Better Test Cases

I could have just called this “or how to keep the testers/QA on your good side”. I have always found that if you involve the testers early, they will appreciate it. Thisis usually because they get a head start on testing or even just that they feel like they are being kept in the picture of whats being built. I always add a section Testing Impact for bigger design documents. The end result is the same though better testing though better test cases.

Helping new hires

Getting new hires to write design documents is a massive benefit (for them!!!). Of course they get thrown in the deep end – that’s what any new hire expects. However, if as a new hire you get to write a dd and it’s reviewed by your manager/peers it’s a good way to ensure you start on the right track and avoid the embarrassing experience of spending days/weeks writing something that is thrown away because it’s totally off the train tracks of the development standards/patterns. Also, having a catalog of dd’s makes it easier for the new hire because they can see the format and the way tat a dd scales with the size of a project. This is related to point above about Avoiding designing mistakes, but for the new hires it has special significance.

*Every good dev team contains at least one wizard.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s