This document contains helpful considerations during the project design phase. If you want to document an already completed project, free to use only the sections you need.
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)
Technical strategy
details the concrete steps and challenges required to get there.
Motivation
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”. It is important to include enough information in this section for the readers to evaluate the feasibility of the proposed solution.
Design proposal
outlines the approach and methodology for achieving the goals mentioned in the motivation section.
Terminology
should include any special terms or concepts that are specific to the project and may not be familiar to everyone on the team.
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)
Low level designed
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
Risk Considerations
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)
Security Considerations
should address how the proposed solution will handle sensitive data, permissions policies, and protection against both insider and external threats.
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.
Testing Scenario
should cover all aspects of the business flow, including input validation, error handling, and edge cases.
Appendices
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent