Creating and using design documentation at Neon

There are many sources on how to design things, but in this article, I would like to focus on describing the framework that we use at Neon for evaluating designs and choosing the one that is best suited for our needs. So read on to find out more about our design documentation and the best practices we recommend.

At Neon, we wanted to make sure that we can have a healthy discussion regarding the important changes to our system and make decisions together. We wanted to avoid situations where decisions are heavily centralised, and engineers feel like they cannot provide feedback for the specific solution (or maybe challenge it in some cases). This becomes even more important as the team grows and new engineers join the team. With this framework and design documentation (we call it D&A internally) we have managed to do just that, with great success.

How our design process looks like

In a nutshell, one person describes the idea (design) in a structured way and tries to provide enough information to justify it. Then, the rest of the team provides feedback and discusses various aspects of the design, so they can eventually decide if this is something that is worth doing or not. However, this is just the TLDR version, the real thing is (as it’s always the case) a bit more complicated.

The framework itself has two main parts. The first part is the design documentation that contains all the important information about the design. The other part is the process that is used to provide feedback and make a decision.

Part 1: The design documentation

Let’s now look at the design documentation template that we use at Neon. It consists of several key parts:

• Goal
• Problem statement
• Current state
• Scope
• Design and the alternatives
• Action items

Below you can find the detailed description for each of these parts of the design template and tips on how to make the most out of your design documentation.

Goal

Here, you need to briefly define the goal of the design – what it is that you are trying to achieve. For example: “We want to build a Joint Accounts feature. This feature is aimed to cater to users who wish to share an account for various needs like family expenses or savings.”

The problem statement

Here, you need to describe the problem that you are trying to solve and why you consider it to be a problem. For example: “We want to split service X into two smaller services. Currently, service X has many features. All these features can be divided into two distinctive groups. One of these groups is being actively developed, while the other is stable and only modified occasionally. Splitting service X into two smaller services will make each of them much easier to understand and maintain and would allow us to have better scaling and customised optimisation.”

The current state

This is the description of the design that you have right now. You should provide enough information to the readers of your design documentation about the current state. This includes a sufficient level of technical details and what are the main challenges or limitations. If possible, include diagrams, pictures, performance data. Whatever you feel would be the most beneficial (depending on the case, of course) – should be included. It should be noted that you need to be precise here – because you are describing the state that you want to change and why you want to change it.

The scope

Describe what will and will not be the part of your design documentation.

Design and the alternatives

Now comes the “meat” of this design documentation – the new design that you want to propose. Again, include enough relevant information, but avoid going too much into technical details, unless it’s necessary.

For example, if we use the previous example with the two new services that are going to replace the existing one, you should list all the use cases that each of these services is going to handle. You might also provide the list of the endpoints that these services need to expose, but you probably don’t need to describe the requests and response objects or provide implementation details (unless there is something very specific that needs to be taken into consideration). However, if there are things like caching, authorisation, integration with third party systems – make sure to describe how the new design would affect them. In some cases, the design could be accompanied by a small proof-of-concept project. This is done to showcase how things really work (there are some projects for which this might be required).

Alternatives

Ideally, one or more alternatives follow the main design. These alternatives consider things like time, scope, and the overall complexity of the solution. You should present them as a list of pros and cons. For example, maybe you don’t have time to fully implement the main design by the release date, so the alternative approach would be to implement the most critical part of the solution and keep the rest of the system in the current state, but then revisit that after the release (basically, deliver the solution in multiple stages). Or, instead of creating another independent service, the alternative way of adding the new feature could be to add that functionality to one of the existing services, to avoid having too many services that your team needs to take care of. Sometimes, it is possible to have no alternatives at all – it really depends on the case.

Additional important aspects

When deciding on the design, several important factors will have an impact on the final decision. For example:

• Is this something that is strategically important for your product?
• Will this have an impact on your customers or on the overall performance of the system?
• Will this solve some issues that the engineering team has been facing, or prevent some future issues?
• Is this simply nice to have?

By taking all this into account, you are making sure that you want to focus on more important, higher-impact decisions first.

Part 2: The process

The process consists of several stages:

Writing the design

This is where most of the work takes place. One person collects all the necessary information and writes the design documentation, using the template presented above. Once the document is done, the author notifies the reviewers and sets the date for the final discussion. This person should make sure to invite all the reviewers or any stakeholders that might be important for this discussion. At Neon, we are utilising Confluence for writing the documents, but any similar tool would do (Notion, for example).

Review

The reviewers read the document and leave their comments. There is a deadline for this – reviewers need to submit comments before the final discussion. The reviewer can also indicate that they don’t have any comments. Reviewers who don’t do any of this – you should remove them from the final discussion. You want to have discussion only with those people who have read the document.

Addressing the comments

The author of the document addresses each comment. Addressing the comments might be as simple as answering the question or providing clarification. It can also involve modifying the document or adding additional content. Each reviewer needs to confirm that their comments have been successfully addressed and mark the comment as resolved.

Final discussion

Once all comments have been marked as resolved, the final discussion can take place. By this time, everyone involved has read the document and provided the feedback. All of this has been integrated into the document as well. The discussion has very clear goals: choosing the best approach for the solution. This is basically, picking between the proposed design and the provided alternatives and resolving any potential roadblocks. Once the discussion is finished and everyone agrees on the next steps, the author of the document can list what these next steps are and assign them to the proper stakeholders. Keep in mind that the author of the document is not necessarily the person who needs to develop the solution. The author is the one who did the research and suggested several potential approaches, but then based on the feedback and the final discussion, the team ultimately chooses the right approach.

Conclusion

Obviously, one of the main values that we get out of this approach is fair and open discussion about any new extension or modification of the existing system. By doing this, you avoid the problem where only one person (or very small group) dictates how things would be implemented and (in the worst case) disregard the opinions of other team members. However, there is another very important thing that this approach will provide: it will allow your senior engineers to be involved in making important decisions.

Encourage your team members to share their ideas

This is particularly important because throughout my career I have often seen senior engineers who felt like their opinion on important pieces of design has been disregarded. Sometimes it was the case, but sometimes they simply did not try to present their solution and provide proper arguments for why it is a good (or better) choice. This approach provides a fair framework where everyone can bring their idea to the table or provide constructive feedback. 

For managers, this is an important tool that they can use as one of the ways to assess someone’s contributions. Engineers (especially senior ones) should be encouraged to present and discuss ideas. This is one of the most important aspects of their work. At the same time, writing design documentation will require the author to think about how to present (or communicate) the idea. Unfortunately, this – communicating ideas – is one of the skills that is often neglected, because some people choose to focus more on purely technical skills, forgetting that good communication is often equally (or even more) important as technical skills. With the consistent use of this framework, you might be able to partially address this concern as well and help your team grow.

If your team needs help with finding great new team members who would help you reach your business goals faster, contact us or check out our IT team augmentation solutions where you can find more information about this topic.

---

Author

Miroslav Lazovic is an experienced software engineer from Belgrade. Over the past 15 years, he worked on many different projects of every size – from small applications to mission-critical services that are used by hundreds of thousands of users on a daily basis, both as a consultant or part of the development team.

Since 2016, he is focused on building and managing high-performing teams and helping people do their best work. He likes discussing various important engineering and management topics – and that’s the main reason for this blog. Besides that, Miroslav has quite a few war-stories to tell and probably far too many books and hobbies. There are also rumors of him being a proficient illustrator, but the origin of these rumours remains a mystery.

– Backend TL@Neon and Dev. Advocate @Holycode