10 Reasons why writing a design for your feature is a good idea

It is no secret that planning usually improves final results, as well as optimizing the process itself.

However, during my career as a software engineer and engineering team lead, I have found myself countless times explaining the importance of design to my colleagues.

At my work place we are writing a design document called a DR which is an abbreviation that stands for a Design Review. DR is a short wiki document, presenting a design for a new functionality that was requested to be done. The scope of our features varies between a few days to a few weeks. If the scope exceeds this time, the feature is broken down into a series of a smaller features, each with it’s own DR. Once the initial DR is completed the developer shares it with the entire company, via email, a F2F presentation or both.

It’s interesting that the importance of writing a DR is called into question, not only by fresh engineers at the start of their career, but also by experienced developers. Both tend to treat it as a bureaucratic time killer, and think their time would be better invested in development.

There may be various reasons why they feel that way. The design reviews they are used to do, are not triggering the right discussions, too detailed for out of context developers to be involved in, or too abstract resulting in being too obvious. It also may be that the review part is ignored, there is almost no point in writing down a design without a platform to review it (may it be the F2F meeting/email or a WIKI document).

I happen to think DR’s are an invaluable part of feature development, wanted to share, and will attempt to convince you likewise.

There are numerous explicit and implicit advantages of writing and sharing one’s design. I have chosen to present you the few I find to be most compelling.

1. Gain a deep understanding about what you are about to do.

Writing a DR almost always triggers research, it forces developers to think about the feature in depth from start to delivery. They must now consider the feature in terms of what is different from other features they have done, what the possible pitfalls are, are there any unknown parts, how will the flow work, how will it influence: performance, other features, different platforms. I truly believe that once you have to explain something to others, you force yourself in to a higher level of understanding of the subject.

2. Be certain that you are on the right track.

Once you have invested thought in how best to implement and shared the plan with your colleagues, prompting a discussion and amendments to your plan, leaving you with a more concrete, well-informed direction.

You can now be much more confident that you have a solid plan and that you have not missed a better solution.

3. Declare ownership/expertise/ mark your territory.

Once you share a design which contains:

• An interesting/big refactoring of some component
• A new technology used
• A new component introduced
• A solution for a known problem

From now on, for all those who read your DR, you are going to be the authority in this area, someone they can come to for advice. Not many people consider this angle of it, but “a great DR is great PR”.

4. Sync the stakeholders.

There may be a few sync points for your feature, such as a kick-off meeting, spec review, sprint planning etc… DR is falls into the same category. It is the last stop before code is written, meaning the last opportunity for your stake holders to understand what is going to happen once you dive into coding and make sure that you are all on the same page.

A great experiment can be to ask the developer writing the DR to explain the product motivation of the feature in their own words; you will be amazed to discover the discussion this creates between the developer and the product manager. I have often been witness to such a discussion, and have seen features evolve, cancelled and born as a result of being suggested by the developer whom now better understands the aim and motivation of the original feature in the first place.

5. Mapping owners.

I don’t always have time to fully read my colleagues’ DR’s, but I always find the time to read the title and try to understand the area/component they are changing/revising. As a result of this I have a mapping in my head of which people are involved in which areas.

This helps me any time I need advice or a consultation for those topics. I know whom I should talk to, who is most relevant. It is also a great tool for me as a dev team lead. When my schedule is swamped, which it is more often than not, and I have to provide tech/product related advice to my team, I always know who has the freshest information on the given subject. I can refer them to those I know were the last to gain experience in the area.

6. Share your solution to give advice.

Maybe you solved a problem that others might also be facing — Great, now they can benefit from your solution. They can explicitly use your solution, solve in a similar manner, or perhaps use your functionality, data, API or even just the approach , helping them in handling similar problems.

7. Share your solution to get advice.

Alternatively, you may be solving a problem that is already solved — It may be that somebody in your team already faced a similar challenge. I’ve seen help come in various forms, from a suggestion to use an existing open source solution matching your pain, to a component written by somebody in your organization that can handle part of your task, and even a fully developed feature that has exactly the functionality needed.

8. A structured way to think about your feature.

There are a few integral questions relevant to nearly all software features/ component designs that the majority of us tend to leave out of the planning phase.

I have the solution for you, from deep in my developer soul — automation :) Create a template! It doesn’t matter if it’s a doc,a pdf or an internal wiki page, just make it part of your process.

To help you start, here are a few headers from the template we use in our organization, thus making sure the developer considers them and gives them the proper attention.

• Motivation, Hypothesis, Goal — · As mentioned earlier, these generate discussions with the product manager, resulting in a deeper understanding of the feature and the business as a whole.
• Requirements — To make sure you understand what the product really wants to happen, and that there have not been any miscommunication.
• Performance — How is your new component is going to influence performance? How fast will the data grow? What is the SLA of the API’s you plan to use? Does the architecture of your feature match the flow, or it is built from existing code bricks, that are not optimal for the new flow? Maybe adding a bulk option to your query will save some time? Etc.
• Platforms — Examine how your feature is going to handle the relevant platforms. Are there different browsers, different OS’s, should it work on mobile devices, or called from an API?
• Operational aspects — Maybe there is a new table that is going to grow so fast that you need new dedicated hardware or a cloud solution? Maybe you plan to have a migration with a big impact on your production environment, which means you should consider running it during a time period where you have the least amount of user traffic?
• Testing strategy/Risks — Need I say more?
• Monitor/Debugging tools — Debugging production is not always trivial, it is always worth investing time thinking how you can make your life easier when shit hits the fan, ensuring you have a good way to understand what is going wrong leading to a quicker solution.
• CMS — Not every change that should be done to your product, must be developed and deployed. Sometimes in the early phases of a feature, you can identify areas that are CMS manageable. Of course, it is always a question of ROI.
• A few more…

9. Documentation.

This really depends on the platform you have chosen for your DR’s, at my workplace we use an internal WIKI, which really helps, providing an easy way for searching, referencing and giving feedback. The wiki can then be returned to any time someone needs to better understand the feature.

I am not innocent, we all understand that code is not static, it evolves, components are refactored all the time, and the initial DR is rarely updated to reflect those changes, but from my experience, usually the basic information survives the test of time and can still be immensely helpful.

I think code should be self-explaining, and this is not a substitution for the code being written in a clear way. But the general things like table names, feature kill switches, external API’s or even an algorithm overview, can be really helpful for your partners like NOC/Management/Product /DevOps who do not have access to the code, but have to provide sometimes quick answers/solutions .

10. Raise a discussion.

Discussions are a great platform to share knowledge, to learn, and to hear new opinions. New ideas are born, new directions taken. You get to know your colleagues, what and how they think, and both sides end up walking away with broader horizons.

Bottom line

The advantages, of integrating design reviews into the development process can be grouped into 3 groups:

1. Learning platform.
2. Safety net.
3. Optimization tool.

Take some time to think if the DR process in your organization serves those purposes and it will help you understand the advantages and motivate others so you can benefit from them.

I would be happy to hear what you think. Are there any advantages I missed? How does your workplace manage design?