Writing efficient frontend design documents

Frontend design documents are an essential part of the software development process, but their importance is often overlooked in front-end development. While backend teams commonly write design documents during the planning phase, front-end design documents are undervalued and ignored, resulting in poorly designed user interfaces and wasted development time. This article aims to raise awareness of the significance of front-end design documents and offer guidance on how to create effective ones that can enhance the quality of your front-end development projects.

Why do we need frontend design documents?

Reason #1: Get stakeholders on the same page

The tremendous power of the written word makes it much harder to misunderstand one another.

The Staff Engineer’s Path

When multiple people are working on the same project or feature, it can be challenging to ensure that everyone has a shared understanding of the goals and requirements. A design document can provide a written plan that helps stakeholders agree on whether the team is solving the right problem, and whether their assumptions about other teams and existing systems are correct. This is especially important when teams are distributed across different locations or time zones.

Additionally, different teams may have conflicting priorities or requirements, and a design document can help identify these issues early on in the process. By creating a design document, teams can cheaply iterate and ensure that everyone is aligned before investing significant time and resources in development. This can help prevent costly mistakes or rework down the line.

Imagine discovering one month before the launch date that the new API you need to integrate with behaves differently than you expected or returns a different output. I recall an example from my days at AWS when our front-end team had to integrate with a third-party service’s API. We expected to see some critical information displayed as part of the resource ARN, but the third-party team expected us to call an additional API to describe the resource. However, we couldn’t make the additional call due to performance concerns (we had to display thousands of resources in the list), which caused a chain of escalations involving UX design, our service backend team, the external service team, the manager chain, and the frontend lead (me). This problem could have been avoided if we had a design document reviewed beforehand.

Reason #2: Distributing the work

When leading a front-end development project with a team, it’s crucial to share your vision of the high-level design with the team. This includes breaking down the work into manageable chunks of functionality that can be created in parallel by sub-teams, each with its own set of milestones and even its own design document.

Splitting the work into workstreams can help ensure that progress is made efficiently and that the project stays on track. Workstreams can be thought of as separate phases, where a team completes a large piece of work, reorients, and then kicks off the next stage of the project. These streams may depend on each other at key junctures, and some streams may not start until others are completely finished.

By creating a design document that outlines the high-level design and the different workstreams involved, you can distribute the work more effectively and ensure that each sub-team has a clear understanding of its responsibilities. This can help prevent confusion and reduce the risk of delays or miscommunications that could lead to wasted time and resources.

Reason #3: Reduce the risk of “bus factor”

By distributing the work through workstreams and documenting it in a design document, you can also reduce the risk of a ‘bus factor’. In other words, if something happens to the project lead or other team members, the next person to step into their role would not have to start from scratch. They can refer to the design document and pick up where the previous team left off, ensuring that progress continues and the project stays on track.

Reason #4: Build a history of the project

Another benefit of having design documents is to build a history of the project. Like a file version in Git, a design document serves as a point-in-time snapshot of the project’s architecture, which can be extremely useful for understanding why certain decisions were made in the past. For failed projects, design documents can serve as a basis for new beginnings or a good source of information to learn from mistakes in the future. By keeping a record of the design decisions, it’s easier to understand how the project evolved over time and what factors contributed to its success or failure.

By having a detailed design document, new team members can quickly get up to speed on the project’s architecture, design decisions, and implementation details. This can reduce the time it takes for new team members to become productive and ensure that the project’s quality and consistency are maintained over time.

Reason #5: Personal interests

Another reason why design documents are crucial is for personal interests. If you’re aiming for a promotion or looking to showcase your contributions to the company, having a well-documented design document can be extremely beneficial. While a list of submitted PRs can demonstrate your technical skills, it doesn’t provide evidence of your ability to manage a project, lead a team, shape the work, or approach complex problems. A design document can serve as a record of your contributions, including your thought process and decision-making, which can be valuable evidence of your leadership abilities. Even if you didn’t contribute to the project by coding, being the lead who kick-started a big and complex project is already 50% of its success.

Types of design documents

Design documents can be categorized based on their level of detail and purpose. The level of detail can range from high-level design documents, which provide a broad overview of the system architecture, to low-level design documents, which delve into the specifics of how individual components will be built. The purpose of a design document can also vary, with some documents focused on outlining the technical vision of the project, while others may focus on the technical strategy for achieving specific goals. Each type of design document serves a specific purpose and is created at a different stage in the project.

High-level design (HLD)

High-level design documents provide a broad overview of the project’s architecture, defining the main components and their interactions. This type of document should answer questions such as what the key features of the application are, how they are connected, and what technologies will be used to develop them. High-level design documents are typically created during the planning phase of a project, and they serve as a roadmap for the development team.

For example, during a brainstorming session with various stakeholders, a front-end lead might work with the project manager, back-end team lead, and UX designer to create a high-level design document. At this stage you don’t need to have fancy mockups from UX team -the entire system UI can be literally drawn on the whiteboard. High-level design document for this feature would outline the project’s goals, high-level features, business flows, and third-party integrations. While the document wouldn’t necessarily cover all the implementation details, it would provide a bird’s-eye view of the functional units that need to be built, how they are connected, and how they can be integrated into the existing system.

In this document, you might be interested in highlighting the following:

• project milestones (e.g., “Build JSON policy editor widget”, “Build cross-region copy flow”, etc)
• for each milestone, define a high-level component tree with state-related concerns (if you are using a state management system like Redux, it might be important to highlight what data goes to the global state vs. what data is isolated in the component’s local state).
• If you are using distributed frontend architecture (micro-frontends), you may apply Domain-Driven Design methodology to draw new boundaries in the architecture. In other words, whether this new feature fits into existing subdomain/bounded context or requires a brand new micro-frontend app to be developed and deployed. If the latter, then how it will communicate with other apps, and what events will represent these communication concerns?
• API integration and permission model: what permissions are required to call specific API, and what would be the UX behaviour in case of lack of permissions (e.g., redirect to page B)
• Known limitations and uncertainties (e.g. “We won’t be able to use ModalA component because it requires admin account permissions to build the view. We will have to wait for Auth team to release delegated admins type of account” or “If we decide to use the same advanced JSON editor as we on PageA, we need to investigate how we can manage shared third-party dependencies in the future”). This kind of considerations can be really useful for engineer who will be working closely on the low-level design for this milestone.
• Define business/operational metrics to track
• Rough estimates for each milestone (preferably, build a workstream diagram that will highlight dependencies between milestones, order of execution and level parallelization)

High-level design documents are often reviewed multiple times to ensure that all high-level features are feasible to implement within the given timeline. During the review process, stakeholders may identify which features can be cut and which ones should be prioritized for launch in the project’s next phase. This next phase could be represented by different milestones, such as “GA Preview -> Full GA” or “MVP -> v1 -> v2”. While it may not be necessary to know the exact timelines of these phases, it is important to have a clear understanding of the business value of each phase and how it aligns with the overall project goals.

High-level design documents are typically more useful for complex features or projects that involve multiple teams or systems. For smaller features or projects with fewer dependencies, it may be more efficient to start with a more detailed design approach. The level of detail required for a design document can vary depending on the project’s size, scope, and complexity. It’s important to strike a balance between providing enough information for the development team to understand the requirements and leaving room for flexibility and iteration as the project progresses.

Low-level (detailed) design

Detailed design documents provide more in-depth information about the project’s architecture and implementation. These documents include technical specifications, diagrams, and code snippets to guide the development team. They are usually created after the high-level design documents have been reviewed and agreed upon.

Usually high-level and low-level designs are maintained by different authors. But if your front-end team is small and you don’t have a lot of opportunities to delegate, it may not be necessary to create a separate low-level design document. In such cases, you may include more detailed information in the high-level design document or create a hybrid document that includes both high-level and low-level details. The level of detail in the design documents should be appropriate to the scope and complexity of the project, and should provide enough guidance to the development team without being overly prescriptive.

What details you can include in your design document:

• Enhanced component tree with more fine-grained components and well-defined state shapes and component contracts
• If your app requires complex API orchestration, you may benefit from having a detailed flow diagram to highlight the order of API execution and when to update components with new state
• Error handling for special use cases
• Performance concerns, such as caching and network optimization
• Security concerns, such as permission schemas to be publicly shared, storing sensitive information in the local storage/IndexDB, CSRF protection, CSP headers
• Alternative design considerations
• Technologies and tools to be used
• Test scenarios (usually speaking about E2E tests here)
• Accurate estimates of work and level of parallelization

The low-level design document is primarily intended for the development team and their technical lead, as it includes more technical details and implementation specifics. It may also be shared with other stakeholders such as the product manager or UX designer if they need to review and provide feedback on specific implementation details. However, the main audience for this type of document is the development team itself.

Technical vision

Technical vision documents outline the long-term goals for the project’s technology stack and infrastructure. This document describes the future as you’d like it to be once the objectives have been achieved and the biggest problems are solved. Describing how everything will be after the work is done makes it easier for everyone to imagine that world without getting hung up on the details of getting there. You can write a technical vision at any scope, from a grand picture of the whole engineering organization down to a single team’s work. Your vision may inherit from documents at larger scopes, and it may influence smaller ones.

A technical vision doesn’t set out to make all of the decisions, but it should remove sources of conflict or ambiguity and empower everyone to choose their own path while being confident that they’ll end up at the right place.

There’s no particular standard for what a vision looks like. It can include:

• High-level architecture of the project
• Set of guidelines and principles for the team or entire organization (e.g., testing best practices, Redux shape vision, applying feature-sliced design, etc)
• Summary of decisions being made
• Definition of the processes (e.g., on-call rotations, addressing technical debt, etc)

Again, the main goal of this document is to describe a clear (have a biased or fixed perspective and be resistant to considering other viewpoints or opinions) and realistic (no unicorns) optimistic future that meets the needs of your team/organization.

Technical strategy

Technical strategy documents provide guidance on how to achieve the goals outlined in the technical vision documents. It should include a plan of action describing the step-by-step process of achieving your vision. While a technical vision is more focused on the end goal and ideal state, a technical strategy details the concrete steps and challenges required to get there.

For instance, if you’re planning to migrate your project to a new architecture and have a vision for how it should be structured, your technical strategy document might include:

• A migration approach, such as whether to migrate all at once or use a strangler pattern
• A phased plan for the migration, including guiding policies for each phase
• Identification of the challenges that will arise in each phase and proposals for overcoming them, such as success criteria or a definition of done
• A rollout plan for releasing the migrated project to users.

Frontend design document template

Design documents often vary depending on the specific project and the team creating them. As such, there is no universal template or one-size-fits-all approach to structuring these documents. However, I can share some design document templates that I personally use when creating features.

Project metadata

Project metadata is important information about a document that provides context and helps with version control. This includes the name of the author, the date the document was created, the date of the last modification, and the current status of the document (such as Draft, Reviewed, or Discarded). If the document is a low-level design, it can also include a link to the high-level design document for reference.

Example:

Motivation

The motivation section of the design document should provide a brief overview of the problem that the feature or project is aiming to solve. It should focus on the “what” rather than the “how”, and can be just a few sentences in length. The purpose of this section is to provide context and set the stage for the rest of the document. Do not include implementation details of your design and design/technical decision here – it would be addressed later in the document.

Terminology

The terminology section of the design document should include any special terms or concepts that are specific to the project and may not be familiar to everyone on the team. This can include industry-specific jargon or acronyms, as well as any schema definitions or technical terms used in architecture diagrams. The purpose of this section is to ensure that everyone working on the project is using the same language and understanding the same concepts.

Design proposal

The design section of the document outlines the approach and methodology for achieving the goals mentioned in the motivation section. It is important to include enough information in this section for the readers to evaluate the feasibility of the proposed solution. Visual diagrams are helpful in conveying complex ideas and should be included whenever possible. The text should highlight the key points and emphasize what is important. In some cases, it may be necessary to describe the order of execution in the diagram by assigning numbers to connecting arrows and providing additional information below the diagram. Avoid repeating the same information in both the text and diagrams.

As mentioned earlier, visual diagrams are an effective way to convey complex ideas. For instance, in my recent article, I demonstrate how you can create an infrastructure diagram using AWS Application Composer in just a few clicks. This tool can be extremely useful in creating clear and concise architecture diagrams that effectively communicate your design. Additionally, it can help you create a Proof of Concept for your architecture that your colleagues can interact with.

Alternative designs

The “alternatives considered” section is where you demonstrate (to yourself and others!) that you’re here to solve the problem and you aren’t just excited about the solution. If you find yourself omitting this section because you didn’t consider any alternatives, that’s a signal that you may not have thought the problem through.

The Staff Engineer’s Path

When presenting alternative designs, it is important to highlight the tradeoffs of each approach and explain why you ultimately did not recommend it as your proposed design. This will help your readers understand your thought process and reasoning for choosing a particular solution.

Risk considerations

The risk considerations section should address any potential risks associated with the proposed design. This includes having a contingency plan in case the original design does not work, as well as identifying any potential side effects that could impact the existing architecture (e.g. performance, usability concerns). It is important to be transparent about these concerns and worst-case scenarios, as it can help to identify and address them before they become actual problems. Providing this information can also help to build trust with your readers and demonstrate that you have thought through the potential risks and have a plan in place to mitigate them. Sometimes, your readers might provide you some useful ideas how to address them!

Security considerations

The security considerations section of the design document should address how the proposed solution will handle sensitive data, permissions policies, and protection against both insider and external threats. It is important to be transparent about any potential security risks and provide a plan for mitigating those risks. If your organization has a well-defined process for addressing security concerns, you should include a security threat model and review it with your security engineers.

Operations

The operations section of the design document should address how the system will be operated once it is deployed. This includes business metrics, such as who will use the feature and how it will be used, as well as system health monitoring, such as ensuring that page loads successfully, tracking the latency of user actions, and monitoring web vital metrics. It is important to include details on how the system will be monitored and maintained, and any tools that will be used to ensure that the system is operating correctly.

Testing scenario

In the testing scenario section of the design document, it is important to define the happy and sad paths for each business flow in the new project. This information can be used as a source of truth for engineers writing end-to-end tests and for QA engineers conducting manual tests. The testing scenarios should cover all aspects of the business flow, including input validation, error handling, and edge cases. It is also important to document any known issues or limitations of the system and to include steps to reproduce them. By defining these testing scenarios, you can ensure that the project meets the requirements and functions as expected.

Appendices

Appendices are optional sections in the design document and are typically used to provide additional information that may not be directly relevant to the core design. Examples of information that can be included in the appendix section are non-essential architecture diagrams, UX mockups, code snippets (can be even pseudo-code), links to tools documentation, and other related design documents. This information can be useful for readers who want to explore the design further or who want more detailed information about specific aspects of the design. However, it is important to ensure that the core design is fully explained in the main body of the document and that the appendices are not relied upon to convey critical information.

Conclusion

In conclusion, a well-written design document is a crucial component of any software development project. It provides a roadmap for how the project will be executed and helps to align all stakeholders on the goals and objectives. A good design document should include clear and concise information on the problem being addressed, the proposed solution, and any tradeoffs that were considered. Visual diagrams can be especially helpful in communicating complex ideas.

It’s also important to consider risk and security considerations, as well as operational requirements and testing scenarios. By including all of these components in the design document, you can ensure that everyone involved in the project is on the same page and has a clear understanding of what needs to be done.

Overall, taking the time to create a thoughtful and comprehensive design document can save a lot of time and effort in the long run, and can help to ensure the success of the project.