Design Document Part 6 (Another dd found)

OK so here’s another good example and it’s not that’s even called a design document but if it looks like a duck and smells like a duck and quacks – its probably a duck. Same goes here. Look at the section called: The Application Architecture:


Design Document Part 5 (seeking feedback)

A little bit of background for the sample design document (dd) I posted in part 4 :

  • This dd was used for a hackathon project at my work.
  • The original dd was a handwritten 1 page document.
  • I did not really get significant review because it was a solo project (normally I wouldn’t do a dd unless I was seeking feedback).

So the last point is the most important – I used this as a sample because it’s easy to post without any real work details. Normally I send these type of documents via email (or at least a link) and ask for feedback. The other option is to do a demo/presentation and just gather the feedback from that session.

So the type of feedback I am after is:

  • Am I roughly on the right track?
  • Am I using the right frameworks/libraries?
  • Am I proposing to re-use any existing patterns or follow approaches (ie. lets not reinvent the wheel).
  • DB design/modifications can be tricky and seeking advice from DBA’s for DB changes can be very very useful.

Of course, you need to evaluate feedback sensibly but having your manager involved usually makes that an easier process.

Design Document Part 4 (Example design document)

Design Document – iOS Augmented Reality App


The following document outlines the design of a simple iOS application consuming location data from an Azure Webservice (specifically using the latitute and longitude data) to provide an AR experience based on organisations close to the device.

High level Architecture


Major Components

iOS client
iOS App
XCode 6.3 Application written in objective C
Location Services

Web API Controller
WebAPI 2.0 Controller based on the EF model (see below)

Entity Framwework
EF Model Generated from the SQL Database (see below)

Simple 1 table database containing customer information


Design Documents Part 3 (when to write a design document)

I’ll keep this post pretty light. Here are the conditions that I use when to write a dd:

  • Junior developers for most tasks (again remember some design documents are just a few dot points)
  • Any developer when building a new pattern, system or new functionality that has not been built by the team in the past.
  • Any developer when building something that has a high degree of risk (high risk can occur when deadlines are really tight, production or development environment is not stable etc…)

So the point is you don’t need to write dd’s for everything. If you are an experienced developer building something based on an existing pattern – you really should not need to do a dd.

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.