Design Document Part 10 (What makes a good design)

I came across a great article recently by Scott Hackett: 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.

“You should be able to list at least one compelling reason, related to the requirements, for why a design decision was made.”

(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.




Design Document Part 9 (Design Docs and SCRUM)

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]

  • As a way to familiarize the team with new hardware or software
  • To analyze a problem thoroughly and assist in properly dividing work among separate team members.
  • Spikes tests can also be used to mitigate future risk, and may uncover additional issues that have escaped notice.”

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.


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.

Design Document Part 8 (A great small-mid size template)

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.

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).

Design Document Part 7 (template for bigger projects)

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.

Just remember the design document is best if it’s as small as you can keep it.

ProcJam – v0.01 effort

Ok so a late decision to enter procjam 2015, and here is my first attempt at producing a PCG generated song. Its about 95% PCG at the moment. I am using Joy Division as my base text resource and have had some great tutorials to work through that gave me a good start:

Here’s the first effort – please note that there has been some editing (all stated by the use of{ } and the text inside) and comma’s also inserted:



me waiting for something more, as the territories marked

no matter how hard it end where will it

end, where will burn one who goaded you to

give you, you i tried to get to the

power, it’s creeping up just second nature it’s just

second nature it’s just to feel it end, where

will it end where will it end where will

it end where will it end where will it


end these are closed, i can do you see

there i can see all true realities, up slowly

that keep your throats wasted, our respect runs so

plain to get to you, i travelled far and step

outside, an angry voice and bent on water run

through fire can’t take much can’t take much can’t

take, good taste of speed, a taste of waste

their eyes tears in a struggle between right {“when”:DELETED}


we were young directionless, so plain to you see

there i, did you forget saints with your man

traps with habits of waste their eyes tears, as

the blood on their bodies made a request well

out of the room the one who cried we’ll

share a changeling to watch admire the centre of

sadness for the pleasure, oh i’ve seen the blame


with no longer the footsteps i’m,

not afraid anymore i’ve seen blood in lime,

changing our time hoping for something

more as the first light starts to sing

fine only stare in the start

of the past stand tall and apart

{two lines of text:DELETED}