A collection of documents I wrote on design documents last year:Â https://domscode.com/category/design-documents/
Really important to plan ahead – even just a little bit 🙂
I came across a great article recently by Scott Hackett:Â Â http://blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/. It’s a thorough look at the reasons to write Design Documents (dd) and though it’s a few years old now, it covers one of the really important aspects of writing dd’s – What’s a good design? Â Here’s a great excerpt:
“A design will typically be considered good if it fulfills the requirements in a meaningful way. If any aspect of the design cannot be justified, then it is probably worth reevaluating. Many programmers try to incorporate design patterns into their work, and they often add unnecessary complexity. You should be able to list at least one compelling reason, related to the requirements, for why a design decision was made. That reason must then be documented. If you can’t come up with a clear reason for a design decision, then it is probably not adding value.”
(Scott Hackett:2007)
This is really important and it’s usually why I start most dd’s with some sort of problem definition (ie. What are we trying to solve? or even what are we trying to build?). If you can at least point your design to that – you are at least focussing your design/solution firmly on fixing a problem. That’s a good start.
(Scott Hackett:2007)
I also really like the the breakdown that Scott uses for his dd’s. It is a nice clear separation of areas that can be covered in a dd:
Section 1 – State the purpose of your project/sub-system
Section 2 – Define the high level entities in your design: High level entities are objects, or groups of objects, that constitute major constructs of your design. Good examples of entities are a data access layer, a controller object, a set of business objects, etc…Â
Section 3 – For each entity, define the low level design: This section is where your objects and object relationships are defined…Â
Section 4 – Benefits, assumptions, risks/issues: …”
This breakdown is excellent – it’s not exactly how I split up the dd but it’s logical and it covers a wide range of issues that come up when designing something in Software Engineering.
The last section is really important. It’s a section that you as the developer will not always know at the start. You might actually think “Hey that’s a project managers job”.  I’ll cover that in the next article.
I get asked a lot about how does a design document (dd) fit into SCRUM. There is generally a deal of concern that the dd slows the development process and even concerns that it’s a fall back to waterfall development.
So, just to remind, the dd can be really small. It can be as small as a number of dot points (or a few sentences) in an email or a photo of a whiteboard used in a design/planning session- particularly for small pieces of work.
A dd works well within SCRUM as a the output of a spike. Reminder about spikes:
“A spike in a sprint can be used in a number of ways:[1]
A distinction can be made between technical spikes and functional spikes. The technical spike is used more often for evaluating the impact new technology has on the current implementation.
Source:https://en.wikipedia.org/wiki/Spike_(software_development)
What’s really important about that statement is: “The technical spike is used more often for evaluating the impact new technology has on the current implementation”. This is one of the primary reasons we use a dd. It’s to protect the existing implementation and by seeking feedback from experience developers, tech leads and architects the developer is reaching out and using the experience and knowledge of the development team who generally know the most about the current implementation. They are are in a great position to advise on technical direction to avoid  negative impacts on the current implementation.
The dd does not always have to be produced via SPIKE, but certainly in the case where the SCRUM team is considering a new feature with new patterns/libraries/hardware etc.. then it may well be worthwhile investigating a Spike. I like the dd as an outcome of the spike because it is actually meaningful output and can be accompanied by a prototype. I also like the idea of adding acceptance criteria – that’s really for the tech lead/senior developers/architects to accept as part of their review.
This is a brilliant example/template you can use for a Design Document (dd). It’s a fantastic example and its downloadable as  a word doc.
http://www.jeanpaulva.com/index.php/2011/11/29/low-level-design-document/
Again – in many cases for dd’s this may even to bigger a document (10 pages) than you need, but its certainly similar to a few I have created for a project that is more like 1-4 weeks of work.
Great to see the database design here, because again remember that you want to get feedback for this (particularly from DBA’s, Architects etc…) and getting advice on the DB early is extremely important (DB changes are not always easy).
I’ve written a lot about Design Documents (dd) recently. This is a great template for a really large project – I’ve never used all of these sections but certainly a number of these categories are useful. It certainly gives you an idea for the scope of what a DD covers.
http://blogs.microsoft.co.il/gadib/2010/10/11/technical-design-document-template/
Just remember the design document is best if it’s as small as you can keep it.
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:
http://www.dotnetcurry.com/aspnet-mvc/1199/business-app-html5-aspnet-mvc-webapi-knockoutjs
A little bit of background for the sample design document (dd) I posted in part 4Â :
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:
Of course, you need to evaluate feedback sensibly but having your manager involved usually makes that an easier process.
Design Document – iOS Augmented Reality App
Introduction
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)
SQL DB
Simple 1 table database containing customer information
I’ll keep this post pretty light. Here are the conditions that I use when to write a dd:
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.
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:
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.
Doms Code 