Writing efficient design documents
Crafting efficient design documents: Key concepts for success.
Hey there! Today's article is about something that senior engineers deal with on a regular basis - design documents. Don't worry, it won't take up too much of your time - it's a short read, but covers some fundamental concepts that are worth knowing! Let's dive in.
Design documents can be considered as a formal agreement outlining the requirements of a given project or a system that is solving a clear problem. There are fundamental use cases for any design document, I will highlight some of the key ones here:
Gathering feedback for design improvement: It’s highly unlikely you will always be the most experienced team member of your organization or company. Gathering feedback is a core component of any project and product design to ensure you are creating a system free of design faults and that your design is the most efficient solution to the problem at hand. Feedback from senior members of the team is valuable because they can share and ask a lot of questions that are very important in making sure your design solution is technically sound.
Communication with external teams: Design documents are typically created for engineering systems existing within an infrastructure and ecosystem that impacts the system being designed. Putting that in mind, you need to include all stake holders that can be affected by your intended solution and to make sure the systems you are interacting with won’t have an implication on your design. This is especially relevant for non-technical areas such as privacy and security, where additional requirements may need to be taken into account, impacting the original intended system.
Documenting agreement: Aka.. Signing Off. Keeping track of which version of the design document all affected teams and members approved can be quite challenging especially if you are working on the design document over slack or over a series of video calls. Having all parties sign-off on a given approach can help document that all stakeholders believe that the suggested solution is the most effective one and deal with consequences accordingly.
The subject of leading a design process and composing an effective design document is extensive. However, for the present purpose, I will enumerate some essential aspects that contribute to a good design document.
Have a clear definition of the problem you are trying to solve: Ensure you are solving a clear problem, documenting the impact of solving this problem on your team, organization or the whole company. This can be a very powerful tool in demonstrating the impact of your work and why this problem is worthy in the first place.
Including all the relevant parties: Make sure you include all teams that may be impacted, including external teams as well as non-technical teams. Privacy and security team reviews, for example, tend to be included late in the development process and often results in a set of new requirement that can complicate the design. Incorporating input from other teams as early as possible will make it more efficient to address their concerns and requirements as soon as possible.
Understand the audience and adapt accordingly: Since the design document is intended to be shared with multiple stakeholders. you will need to adapt the language accordingly. Ensure a clear language without any jargon or complicated technical terms early on. Avoid making assumptions that others understand the problem you are attempting to solve or the terminology you are using. Doing so can endure that everyone involved will make a valuable contribution to the document and the design process in general.
Clearly identify the problems with your solution and outline future steps: No solution is perfect, so it is crucial to list all the issues with your solution and potential future improvements. A clear-ish roadmap outlining the scope of your work, what can be delivered in the present, what can be delivered in the future and any follow-up items is essential.
That’s all for today! I've got more exciting articles coming up for you next week where I'll dive deeper into the design process and design documents. I'll show you how to take your ideas from conception to full delivery. So, stay tuned and keep an eye out for those articles!