Pages

Friday, December 21, 2012

Design Documents - My Cheat Sheet...

Design documents are something many of us as engineers write to express how business needs will be solved.  These documents are very important for the business because they are what drives the direction of the current development and explains how the goal will be achieved.  A design document is a very important worksheet which captures the requirements, the domain knowledge, the vision, and the implementation idea of what a team will be working to make a reality.

Unfortunately, I have seen through my career that the continuous process of the SDLC dims the importance of design documents for various reasons.  Sometimes is just time frame, others the people are not interested with the project, and in many of them the person writing the design just doesn't know how to express.  I think the latter is the most common one and my focus in this article.

A design is not expected to be perfect, but it should have the following:
  • Express what the problem is and the business requirements
  • Understand who are affected by the problem
  • How will the problem be solved in a non-technical way
  • Only include important technical details and don't code the design
  • Try to interest your audience by expressing their focus, not yours

I decided writing about design documents after helping a teammate with reviewing his paper.  Below is a "copy / paste" of what I wrote to him.  Hopefully this helps others because writing documents is something that really has aid my career when presenting projects.  Remember, don't get stuck in making it perfect but instead spend the time in making it concise and attractive.

Letter to my teammate:

"In general, you should learn to organized your thoughts when expressing an idea.  It doesn’t have to be perfect, but at least help the audience understand why is this important for them.  This is something I think we all learn as we progress in the career.  The sooner you master this, the quicker you will build professional documents.


Here are some tips:
  • Start your paragraphs with functional description.  Forget the computer for a moment and explain what is needed and how you plan to achieve it.  Technical implementations come and go, but the concept of what we are trying to achieve is the core of the project. 
  • Personally, I try defining an Outline of ideas..  What is needed?  Which bits and pieces are required to achieve it?  Any questions or gaps?  Dependencies to think of?  Possible blockers?  So far I have not talk in computer terms but project focus. 
  • Once I have that outline, I try writing paragraphs explaining the bullet points and connecting the parts.  I go through several iterations myself...
  • The good thing of writing all these functional paragraphs is that later you can go one by one and as you read them, you will get all the ideas and requirements for the technical sections of the document. 
  • Another thing I learned with time is not to get hanged in writing technical information.  Why?...
    • When you are the developer.  You know how to do it and you are better off writing it directly in code. 
    • When you it hand off to an experience developer.  In this case the experience developer knows the tools and knows the system.  Usually they want just the different technical points.  They benefit more from understanding the idea and not how to achieve it.  Actually too much details becomes two cooks in the kitchen… 
    • When the developer doesn’t know the technology.  At that point giving them the code and technical details will not solve anything for them.  They will need guidance and is better to don’t even give them code so they can’t copy / paste it blindly.  And yes, I have seen that happen.  I think the best approach here becomes train and code.  Where you as the designer need to do some code work with the developer so they can learn from you.

Hope you find this helpful.
"


No comments:

Post a Comment