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

Software Engineering Tips

These are tips & ideas I have learn through my career which help me daily with the thought process in situations I am in.  I will like to thanks all those out there who influence me in a positive way.

80/20 Productivity to Effort Ratio

What this means is you can accomplish 80% of the work with about 20% of the effort.  But to accomplish the remaining 20% work you need an 80% effort.

For me this relates to a new software project when building it from scratch.  With little work you build the base architecture but you still have a long way to complete the actual project. Using the architecture you can quickly add most of the implementations for the final project and most certain that will get you the 80% work done with 20% effort.  But then you hit the corner cases and you have to re-think how to implement them trying to follow the existing architecture.  These cases fall in the 20% work left and it takes an 80% work to actually integrate correctly.

Take the bull by the horns!

Early in my career the company was growing too quickly and my manager had too much on his plate.  But he wanted me to grow with him and gave me great opportunities by being the main contact between some of the customers and the company.

I remember being shy because I have never handle business, so I was afraid to fail.   One day he gave me  a great advice saying: "Jon, you have to take the bull by the horns! Be the driver and own it!"

This was like a wake-up call for me.  He trusted me and wanted me to take charge to make things happens.  He push me to think "out of the box" and do things my own way or any other way to get things done.

With time I realize how important is "to take the bull by the horns!".  When you really do it, you own the game.  You are on top of the requirements, design, and implementation.  For me owning it makes the job easier because you know all the angle and probably better than anyone else since you are now the expert.

But just remember that "with power, there comes great responsibilities".  So when you make calls don't take them slightly.  People will look to you and drive by your direction.  So is your fault if you sink the ship.

The Team Lead

When you have a team, it stops being about you and the game becomes being a real leader.  For this you need to try knowing your team, what they are capable of, and what they are interested in.  Help them get their tasks complete by offloading obstacles and avoiding any interruptions which disturbs focus in the main goal.  Trust them because most people really want to do their job right.  At the end, as a group is better to have only 1 person behind (yourself) than 4 to 8 people with their tasks half done.

I have big shoes to fill compare to the team leader I had once.  He always was there for the team and earn our respect for that.  The relative small team we had was able to achieve pretty big tasks in the company because he kept us focus and he handled must of the business needs.  He was a great listener who adjusted to feedback from his peers as well as his team.

Listen & Be Respectful

We all have ideas and see things differently. A problem can have more than one solution, so the trick is listen for ideas.  My best friend and I are totally different customers and designing something brings always the best conversations.  His appreciation for how a solution should work is so different from mine but we both are good listeners and discuss both approaches (by trying NOT to endanger ourselves).  Like I tell my daughter:  "Need to use  your listener ears!".

Not everyone has this skill so sometimes you have to put an extra effort to listening at others first.  That will give you time to think about your proposal and how to present your idea better.  At the end, the only real time to push hard is when a decision is about to be made.  

 

So listen, because there best knowledge is built collectively.

I can do it too...

If one can do it, I can do it too!  This is a motto which have taken me long way.  It got me into computers, electrical, mechanics, building, cooking, design, blogging, and who knows what else.

At the end, trust yourself and try.  Some topics are harder than others.  Especially if is a field you have never dealt with.  But guess what, as you keep trying you will build knowledge and experience.  The things you learn from one field, most certain will help you in another.

It can be scary not knowing and failing.  But guess what, is even more satisfying to learn, stand for yourself, and conquer the subject!

-------------------------------------------------------------------------------

To my readers, thanks for letting me talk to you.

Hope this post helps you and please share your tips as well.  :)

Business over Engineering

This post is a retrospection of a simple concept for managers, but something new engineers tend to struggle with.  I include myself in that group when I recall being a fresh graduate and ready to do things the best possible and try saving the world.. (but I never got the cool flying cape).

Early in my career I struggled with the problem of:
Business > Engineering (business over engineering).

I think this is a very common problem for most technical oriented people.  Why?  Because they know the in & out requirements to solve the problem, but not always have the best resources or scenarios to give it an "engineering solution".  They only know business is pressuring and that causes to deliver a "non-optimal" solution.  :(

I remember this struggle kept me asking WHY?..  Why can't I deliver a "perfect" solution?...

For me to understand this, I had to understand the Business problems.

That's when I realize:
Sales > Business (sales over business).
In order to have business, we need sales.  Why?  Because sales is what makes the $$$ money we all need.  But shouldn't it be Business > Sales because we sell "our businesses".  The reality is NO!  If there is a Sale to make $$$ profits, we will make our business to tap there.

This gets us to pretty much the top of the chain:
Customer > Sales (customer over sales)

Ever heard the expression "the customer has the reason"?  Well, they are the ones $$$ paying after all.  So what the Customer wants is what Sales will try to fit and pitch in for getting the contracts made.  And if an engineer needs to jump through hoops to get there, "they better".

So in summary the chain of business can be summarized as:
Customer > Sales > Business > Engineering

Of course this is a super simplified version of how things work, and devil is on the details of how the actual chain executes.  But it's important for managers to communicate well with their team and get them in the real context of how things work.

Personally I think the key is in identifying where the real engineering is required and separate it from the softer business requirements.  That way your team can focus in building a better core and avoid over engineering functionalities which tend to be more flexible.