how to write an effective design document

7/15/12 How to Write an Effective Design Document "Hello World" The SlickEdit Developer Blog

1/15blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/

Blog Home |Contact |

SlickEdit Website

Wed 2 May 2007

How to Write an Effective Design Document

Posted by Scott Hackett under Programming [81] Comments

Day by day, programmers are able to get more done in less time. With todays high level languages, development

environments, tools and the rapid application development mindset, both programmers and managers have become

accustomed to extremely fast development cycles. Programmers are now more inclined to jump directly into development,fearing that every hour they are not writing code will result in an hour of overtime the weekend before the deadline.

The process of designing before coding is becoming outdated. Documenting designs is becoming even rarer. Manydevelopers have never written a design document and cringe at the idea of doing so. Many who are required to, typically

generate a lot of interaction diagrams and class diagrams, which dont often express the developers thought process during

the design phase. This article will discuss how to do write an effective design document concisely with no special tools, andwithout needing to know UML. It will also discuss why a well written design document is one of the most valuable tools adeveloper can have when entering a new project.

Why write a design document?

A design document is a way for you to communicate to others what your design decisions are and why your decisions aregood decisions. Dont worry if your design is not UML compliant and dont worry if you didnt use a special modeling toolto create it. The biggest factor that determines if your design document is good is whether or not it clearly explains yourintentions.

This presents a problem, however. In order to convey design decisions, you have to consider the audience that you are

writing for. A peer developer will understand why a well-crafted class abstraction is a good design, however your managerwill probably not. Because your peer developers and your manager have different concepts of what makes a design good,there is a need for two design documents; one for peer developers and one for managers. Each document serves a differentand equally valuable purpose as you begin your project development.

If this seems like too much work, its not. This article will show you how to do this through documentation reuse.

What makes a good design?

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 theirwork, 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 cant come up with aclear reason for a design decision, then it is probably not adding value.

Diagrams are a great tool for visualizing your design, but they cannot convey the motivation behind your design decisions.

That is why it is so important to let diagrams supplement your design document, not be your design document.

In addition, it is also extremely important to document any benefits that result from a design decision. By doing so, otherswho read your document will understand what value they can gain. Likewise, any associated risks must also be

documented. More often than not, other programmers have faced the same risks and may have helpful pointers or solutions

that you may not have thought about. By listing these items, you also get others to think about what the potential risks couldbe as well. Teammates will often be able to see potential pitfalls that you didnt see when you created your design. It is

much easier to rearrange some boxes in a diagram than it is to rewrite hundreds of lines of code when an assumption fails orwhen you hit an unforeseen snare during coding. A good design document minimizes unexpected complications by



addressing them before the code is written.

Finally, a document will provide you, your manager and your team with a common vocabulary for talking about the project.A design document can be a powerful tool for a manager because it gives them a view into the project that they dont

normally have the technical expertise to see. By listing the benefits you give your manager tangible items that describe whyyour design is sound. By documenting the risks of your design before development, you pass the responsibility of that risk to

your manager, which is where it belongs.

Lastly, the design document is a written contract between you, your manager and your team. When you document your

assumptions, decisions, risks, etc, you give others a chance to say, Yes, this is exactly what I expect. Once yourdocument passes that stage, it becomes a baseline for limiting changes in project scope. Obviously, requirements are going

to change sometimes, but with a baseline document you have the power to say that no change in scope is due to amisunderstanding of the requirements.

Writing for a Peer Developer

The goal of a peer developer design document is to make sure that your ideas are valid and that your approach works with

what others are doing. When developers dont communicate their plans, disaster is sure to strike when modules or classes

begin to interact. The following items describe a general guideline for writing this type of document:

Section 1 State the purpose of your project/sub-system: In this section, write a few paragraphs that describe what

the project or sub-system does. What is the problem it is trying to solve? Why does it need to exist? Who will use it? Byanswering these questions, you establish the scope of your design. If you find it hard to write a few paragraphs in this

section, then you probably dont understand the domain as much as you should. If you cant fit your description within a few

paragraphs, then perhaps the scope is too large. Use this section as a tool to verify that the scope of your design is

reasonable.

Section 2 Define the high level entities in your design: High level entities are objects, or groups of objects, thatconstitute major constructs of your design. Good examples of entities are a data access layer, a controller object, a set of

business objects, etc Figure 1 shows an example of a .

Figure 1 (click to see full size)

In this section, explain in a few sentences what each entity does. The descriptions dont have to be verbose, just enough to

explain what each blocks purpose is. Be sure to describe your reasoning for defining the entities in your diagram and what

their roles are.

Section 3 For each entity, define the low level design: This section is where your objects and object relationships are

defined. For each object (or set of objects) define the following:

Usage

Describe in a paragraph how the object is used and what function it serves. If an object will interface with an external objector system, it is a good idea to show the interface for the object. Most importantly, you must again describe your thought

process for defining the object as you did. List the benefits and risks. If an object provides an encapsulation, describe in a

sentence why the encapsulation adds value. Use your descriptions to give meaning to the diagrams. They dont have to be

verbose, just enough to get the point across.

Configuration



If your object needs any special configuration or initialization, this is a good place to describe it. If not, this section can beleft out.

Model

Figure 2 shows an example of a to supplement the System Security entity from figure 1. It is not perfect UML, but has some

aspects of UML. Most importantly, it describes the design.


Dont worry about perfection in your models, but be sure to describe exactly what is going on in the diagram. Here, twoconcrete security objects derive from a base security object, and a security factory will create one or the other for a client

depending on the security model of the system.

Interaction

This is also a good section for interaction diagrams. An interaction diagram shows how a set of objects or entities

communicate with each other to perform a complex task. Figure 3 shows an example of an to show how a user might log in.

It uses objects from the various entities shown in figure 1.


Again, this diagram is not perfect UML, but it explains the communication sequence to accomplish a complex task.

Interaction diagrams are most useful when you want to diagram how an object in your system will communicate with anobject in another subsystem. This type of diagram will let the other developer verify that the interaction is correct.

Section 4 Benefits, assumptions, risks/issues: In this section, make a list of 5-6 top benefits of the design, a list ofALL known risks/issues and a list of ALL assumptions. Some of this may simply be rehashing what you wrote in a previous

section of the document. Whats important is getting all of these items into one section so that the reader doesnt have toread the whole document to understand what the benefits, risks and assumptions are.

Never remove anything from this section! As risks become non-risks, document that they are now non-risks and why they

became non-risks. Never erase them from the document. The same holds true for assumptions. You should be able to lookat this section and know instantly what the current risks are to your design.

Writing for a Manager

The goal of a design document for your manager is to make sure that your manager understands what the main entities of



the system are, what the benefits are and, most importantly, what the risks are. The document is your chance to show thatyou understand the requirements and that you have come up with a plan to meet those requirements.

If you have written the peer developer document well, then writing the managers document is simple, because it is justmade up of sections 1, 2 and 4. By dividing the peer developer document up as described previously, the parts which aretypically not meaningful to a manager have been contained in a single section of the document which may be removed.

Conclusion

The hardest part of writing a design document has nothing to do with the writing. The difficult part is working through a

logical design before you get to coding. Once you have a vision of how the objects and entities are arranged, writing thedetails is easy. In addition, it should not require anything more than a word processor and a simple shape painting program.

The positive difference that spending a week on this task can make is unbelievably rewarding in the end. As the adage goes,If you fail to plan, then you plan to fail.

What is a Power Programmer? | Thank you TI-99/4A

81 Responses to How to Write an Effective Design Document

Comments:

1. Ben says: May 10th, 2007 at 5:42 pm

Thanks for the very interessting article. Your blog has become a everyday-must-read to me.

What about a nifty diggit/reddit Button?

Regards Ben

2. Scott H says: May 11th, 2007 at 7:50 am

Thanks Ben! I really enjoy design work and always try to focus my design docs around expressing the decisions Imade and why I made them. Thats an area that a lot of popular design methodologies tend to forget about. Glad you

liked my post, Im really enjoying having the blog here.

3. Jason says: May 14th, 2007 at 10:03 am

Hi Ben,

Glad you are enjoying the blog. As requested, we now have a nifty diggit/reddit Button.

Thanks for the suggestion,Jason

4. Kevin Lynx says: May 25th, 2007 at 12:40 pm

good articles for a beginner .

maybe GRAPPLCE development method is good for everybody here .:)

5. shijeeshlal says: May 28th, 2007 at 9:21 pm



This is a very good article

6. Scott H says: May 29th, 2007 at 8:19 am

Thanks for the nice comments.

You could say this is a design article for beginners, but I also see it as a heads up for more advanced designers andarchitects. Ive seen several projects get architected to a level that left a big disconnect between the architects intentand the programmers interpretation. The thing I was trying to focus on most was not getting caught up in the

formalities of any methodology, but instead focusing on documenting the thoughts that went into the final designthrough words. Interaction diagrams and class models cant relate WHY a design decision was made, which is

something thats lacking in todays formal methods. However, I think that type of information is just as important todocument.

Its also important that developers take ownership of their own design and explain it for others to understand andpossibly learn from. Many developers dont do this because they arent familiar with formal UML and dont feel theneed to take the time to learn it. Documenting your design doesnt require formal UML, it just requires clear

explanation of your decisions and intent in a way your peers can understand. The benefits of that type ofdocumentation for a software project and team are huge, especially in the long run.

7. Nithy says: June 7th, 2007 at 9:43 am

well i am a new software programmer this article was very usefull to me.. i thank the u Scott

8. Justin says: June 13th, 2007 at 2:02 pm

Excellent article, and a very nice breakdown of how to organize things.

One thing to add is this document can be developed in stages. The high-level portion should come first, and beforeyou begin coding (Sections 1 & 2). The detailed descriptions, though, can be filled in as development progresses. If

you really understand the domain, that section should be able to get filled in fairly early in development. If you areunable to fill it in, thats a sign the solution isnt very well defined.

Also, when writing for a manager, the document should focus on the end-user or business benefits of a decision. Anicely segmented and loosely-coupled object model doesnt mean anything to most managers. A robust system thatisolates change, allows parallel development, and reduces interaction problems means much more.

Thanks again for the article! Youve now been added to my reader. Oh, and I found you through reddit gooddecision on the nifty buttons

9. Lucio says: June 14th, 2007 at 10:45 am

Try XP

10. Matt says: June 14th, 2007 at 1:47 pm

Great article. Now if we could just get more managers to request design documents before coding begins

11. jingsong says: July 6th, 2007 at 12:13 pm

logical desigh is the hardest,and the document should make a direct such as uml for software to make a useful one

12. Prakriti says:



August 6th, 2007 at 12:04 pm

This is a very very interesting and helpful Article.

Thanks!!

13. Dave says: August 28th, 2007 at 11:27 am

Nice article. I like the way you emphasize focusing on the intent of diagrams instead of having diagrams for the sake

of having diagrams. Getting into that mindset keeps you focused on communication, which is what design documentsare all about.

The Benefits, assumptions, risks/issues section is also very valuable since it gets people to critique their design and

(hopefully honestly) communicates the benefits as well as the limitations.

One addition you may want to consider is something about deployment. I find that, especially with new products,deployment related concerns are considered too late in the project and can lead to problems ranging from minorly

inconvenient to project-stoppingly disastrous.

14. samrat says: October 11th, 2007 at 5:38 am

This document Is really very helpful for Software documentation

15. Umar Khan says: October 30th, 2007 at 4:16 am

Great article. This article helped alot. Thanks for this article. This is good for starter like me.

16. Emerging Designer says: November 7th, 2007 at 1:49 pm

Thanks, this was really helpfulsome of it doesnt apply to what Im doing, but the overall read was a good one.

Im an interior design student and have to write my first programming document and was wondering if you had anexample or an excerpt that I could use as a resource, in addition to what has already been posted.

17. Scott Hackett says: November 7th, 2007 at 3:43 pm

It really depends on what type of software document youre writing. If youre writing a design document, then the

best approach is to write down as much as you can at once, very stream-of-consciousness style. Draw some

diagrams to support your text, then glue and tape it all together.

Now, re-read it as though you had very little background on the design. This is a difficult step, but has to be done. As

you read, youll realize that you made several assumptions along the way based on your own domain knowledge.Make notes along the way, then go back and revise the document based on them. After your modifications, the re-

reading process starts again.

Youll know you are finished when there is nothing in your document that exists without a clear purpose. Remember,

UML doesnt make a great design document; clear, well defined thoughts do.

Good luck!

18. Emerging Designer says: November 7th, 2007 at 6:31 pm

Thanks for the quick response, Scott. This is good info.



19. Pal says: November 10th, 2007 at 5:53 am

Thanks, this article was I look for..

20. Stephen says: December 11th, 2007 at 12:39 pm

Please I will like some one to give me stuff on programming for beginners to expert stage.

Softwares, websites, tools and lot of information.

21. Rajasekar Mohan says: March 27th, 2008 at 5:50 pm

This is very useful document , which details about the documenting the design.

Regards

Raj

22. Nitin says: April 4th, 2008 at 4:05 am

This is really a good way of USing UML. cheers and good blog

23. GreatX says: May 8th, 2008 at 2:57 pm

nice work

btw im looking for a pro programer in order to help me develope some online private game server

so if you think you can help email me:

[email protected]

24. Infinity says: August 7th, 2008 at 1:48 am

Helped a lot, thanks

25. Harinath says: September 17th, 2008 at 2:54 pm

Found the content very useful and very clear for a deisgner who intends to develop a good and useful design

document.

A Handy and great document to have. .

Thanks for this

-Hari

26. Andy says: October 12th, 2008 at 6:16 pm

Hi, great article. Would be good if you had a real example of the design methods used. I am a student studying

software development and I would find it really useful.

THanks

27. Dennis says: November 26th, 2008 at 12:58 pm

This is a good article, but you might want to proof read it. A few sentences are just not finished: last sentence of



Section 2 -> Figure 1 shows an example of a . of a what?. If you want people to take you serious and serious

about writing, you cant make these rookie mistakes.

28. S says: November 27th, 2008 at 7:20 pm

Hi,

This article is really useful. Thanks a lot.

S

29. Christopher Greene says: December 13th, 2008 at 11:26 am

Im working on a major project with a medical health company. Im desiging new features for a application and this

artical of information just broke down to me what i need to do.

Should you have any info on writing a design doc. for a medical applications doc. for enhancements to features inside

of the software.

Thank you.

30. Anonymous says: December 28th, 2008 at 9:13 am

Very useful and impressive at the least though I would like to know more on what to add to the high level design

document other than the high level diagram of the various components involved.

The low level section has some brief but good explanation on how to go about things but I usually see these two as

two different documents like you said for manager(high level) and for peers (low level or code level).

It would be great if you can provide some direction on this by coming up with a sequel to this article.

Overall, a very good must read for both beginners and seasoned coders as well.

Thanks,

Shaggy

31. Shantan kumar says: January 5th, 2009 at 2:42 am

its really useful article and would be better for fresh engineers if you had a real example of the design methods used.

thank u

32. Bobbie-gail Gayle says: February 8th, 2009 at 8:17 am

Thank you for this article i found it very useful as I am a final year student at univ and design is a part of my final

report.

33. Dawn says: February 23rd, 2009 at 8:57 am

Excellent Article

This has really helped me as I am currently producing a design document for my final year project.

Thanks



34. Suresh Arul says: April 14th, 2009 at 11:14 pm

Hi, Im currently on a team implementing Microsofts EPM in a Medical & Research Centre. Do you have samples ofdesign document for an EPM implementation as it would be very useful.

Thanks

35. chirimambowa says: April 18th, 2009 at 2:56 am

Well digested perspective on the whole idea. refreshingly succinct.

36. khurram says: May 14th, 2009 at 1:47 am

its an interesting article which proved to very fruitful in constructing design document. if u could explain it with little

example it will be even more beneficial

37. Anonymous says: May 21st, 2009 at 3:54 am

GDFGD

38. sreenivas says: July 25th, 2009 at 4:53 am

Excellent design document who are planning to design intaillsy.

39. murali vikrala says: November 25th, 2009 at 2:06 am

Appreciate the effort you have taken to explain about the design document and its importance.But I think as a add on

to this article, if you could expalin the same thing taking some thing as a case study would be more beneficial toall.Looking forward for your article.Great Job.

40. Pixelschlchter says: December 6th, 2009 at 6:06 pm

Nice article! Actually includes quite a few important things others Ive read so far fail to mention, especially the part

on justifying every design idea. Thank you much!

41. kyle says: January 4th, 2010 at 7:34 pm

Freelancers dont need this

42. Subi says: January 14th, 2010 at 3:13 pm

Nice article its really help me a lot.

Thx Keep posting up.

43. Bum says: February 11th, 2010 at 6:31 am

We all need to fuck some ASS =]

44. bobby says: February 20th, 2010 at 5:27 am

Nice artical it helped us a lot we are students of a university and have a DBT project which we have to handle on our



own.we were in search of some sample and went through your artical which helped us a lot

Thank you once again

45. Anonymous says: March 13th, 2010 at 2:06 am

i am trying to design something to disable a phone during driving but enabling a phone if your in a crash or if your car

is being jacked

46. Anonymous says: May 11th, 2010 at 3:25 am

thankes this full information iam yordanos

47. srividhya says: June 2nd, 2010 at 9:29 am

hi ,

The article is very informative. I am a new software programmer.I have to prepare a Design document in short time.

this article gave enough information about design process.

Thanks and Regards,

srividhya.

48. Anonymous says: July 14th, 2010 at 2:15 am

This artical is really nice. Thanks

Rag,

Brahma

49. bizmedical says: September 2nd, 2010 at 10:00 pm

Quality medical web design plays a critical role in modern medical communications. An effective logo is thefoundation of marketing any medical practice.

50. realhossam says: September 13th, 2010 at 10:20 am

you are good, I am now really a senior programmer

51. Munna(i's) says: November 13th, 2010 at 8:35 am

Very nice. I think its better to declare more and more examples for different sections. Good work

52. Ofer says: February 18th, 2011 at 5:12 am

Great resource, learned from it. Keep on the good job.

We are writing a new documentation to our services and i found your short article very helpful

53. klohare says: March 21st, 2011 at 2:20 am

nice one gives what to include detailsthanks.



54. sujeesh says: June 1st, 2011 at 3:53 am

Very good article . It would be even better, if there is a sample downloadable document for a particular requirement.

55. arjun says: July 16th, 2011 at 1:46 am

This is really helpful

56. Anonymous says: October 2nd, 2011 at 2:07 am

good article helpfull. Any once can give a sample document

57. Shahid says: October 13th, 2011 at 2:52 am

Nice article but need a simple real example to complete.

58. Katie says: May 21st, 2012 at 5:58 am

This is a great article ! I will try this.

Leave a Reply

Name

Mail (will not be published)

Website

XHTML: You can use these tags:

Submit Comment

Trackbacks & Pingbacks:



1. Pingback from links for 2010-02-02 | Visualrinse | Design and Development by Chad Udell February 2nd, 2010 at 7:05 pm

[...] How to Write an Effective Design Document The process of designing before coding is becoming outdated.

Documenting designs is becoming even rarer. Many developers have never written a design document and cringe at

the idea of doing so. Many who are required to, typically generate a lot of interaction diagrams and class diagrams,

which dont often express the developers thought process during the design phase. This article will discuss how to

do write an effective design document concisely with no special tools, and without needing to know UML. It will also

discuss why a well written design document is one of the most valuable tools a developer can have when entering anew project. (tags: documentation specification process) [...]

2. Pingback from Iona.LABS links for 2010-02-02 February 2nd, 2010 at 8:24 pm

[...] How to Write an Effective Design Document The process of designing before coding is becoming outdated.

Documenting designs is becoming even rarer. Many developers have never written a design document and cringe at

the idea of doing so. Many who are required to, typically generate a lot of interaction diagrams and class diagrams,

which dont often express the developers thought process during the design phase. This article will discuss how todo write an effective design document concisely with no special tools, and without needing to know UML. It will also

discuss why a well written design document is one of the most valuable tools a developer can have when entering a

new project. (tags: documentation specification process) [...]

3. Pingback from Game Design part 1 Teknolized February 23rd, 2010 at 5:30 am

[...] -Slick Edit How to Write an Effective Design Document http://blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/ -Chris Crawford The Art of Computer Game Design [...]

4. Pingback from Resources MMORPG May 9th, 2010 at 2:20 am

[...] http://blog.slickedit.com/2007/05/how-to-write-an-effective-design-document/

http://www.gamedev.net/reference/design/features/makegames/ [...]

5. Pingback from Ezra Velazquez ITP Fantasy Device September 25th, 2010 at 2:44 pm

[...] This process was based off the blog entry How to Write an Effective Design Document [...]

6. Trackback from Confluence: Parsek April 14th, 2011 at 10:37 am

How To Write IT Technical Documentation

Why write a technical documentation? You will probably wont support your own work for ever. You will probably

forget what you done and way. Writing documentation helps you to rethink and order your own code. Who Are You

Writing For?

7. Trackback from Confluence: Parsek April 14th, 2011 at 10:41 am

Technical documentation

Content Osnovni napotki Rabimo tudi shemo sistema (s kvadratki) tako fizino kot logino Pri pisanju dokumentacije

naj se ima v mislih,

8. Pingback from Effectively Organize Your Games Development With a Game Design Document | Flash Video

Traning Source November 11th, 2011 at 8:04 am



[...] Part 1 and Part 2; the self explanatory Creating a Great Design Document; and a more general How to write an

effective Design Document, which isnt about GDD, but about software [...]

9. Trackback from unifi December 12th, 2011 at 7:50 am

unifi

[...]How to Write an Effective Design Document "Hello World" The SlickEdit Developer Blog[...]

10. Trackback from empresa de reformas en Barcelona December 19th, 2011 at 11:45 am

empresa de reformas en Barcelona


11. Trackback from Mirth Solutions December 19th, 2011 at 3:36 pm

Mirth Solutions


12. Trackback from Sitecheaper.com | Cheap Website Services December 20th, 2011 at 8:03 pm

Sitecheaper.com | Cheap Website Services


13. Trackback from empresa de mudanzas December 24th, 2011 at 5:47 am

empresa de mudanzas


14. Trackback from masterpapers review December 28th, 2011 at 10:46 am

masterpapers review


15. Trackback from empresa de reformas Barcelona December 31st, 2011 at 1:37 am

empresa de reformas Barcelona


16. Trackback from auto electrician January 7th, 2012 at 9:45 am

auto electrician


17. Trackback from How to become ITIL certified February 18th, 2012 at 2:26 pm



How to become ITIL certified


18. Trackback from interior decor March 4th, 2012 at 5:43 am

interior decor


19. Trackback from Confluence: Parsek March 18th, 2012 at 4:14 am

Technical documentation

Content Sploni napotki Zakaj?

20. Trackback from click here March 21st, 2012 at 12:16 am

click here


21. Trackback from March 25th, 2012 at 1:31 pm


22. Trackback from seo April 4th, 2012 at 4:02 pm

seo


23. Trackback from ecommerce April 18th, 2012 at 2:31 am

ecommerce


Archived Entry

Post Date :

Wednesday, May 2nd, 2007 at 10:25 am

Category :Programming

Do More :

You can leave a response, or trackback from your own site.

Free Trials

SlickEdit

SlickEdit Core for Eclipse



Search

Search for: Search

Follow SlickEdit

Recent Posts

Making a Difference with Software

Running with Least Privilege: Software VegetarianismA Few of our Favorite Things

How to set up SlickEdit to manage LibreOffice source tree

Philips Keyboard Guide to SlickEdit (with Vim emulation)

Archives

Select Month

Categories

Code Editors

Dev Management

Macro ProgrammingOther

Productivity

Programming

SlickEdit Games

SlickEdit Products

Technology

Uncategorized

"Hello World" The SlickEdit Developer Blog is powered by WordPress 3.4 and delivered to you in 0.711 seconds using 28 queries. Theme: Connections Reloaded v1.5 by Ajay D'Souza. Derived from Connections.

how to write an effective design document

Documents

good design

design good

design decisions

design documents

design patterns

written design document

process duringthe design

decisions aregood decisions