awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: add scope breakdown section

Browse Source
This commit is contained in:
Sheen
2025-06-13 17:11:02 +00:00
parent 23a7c1b8cc
commit 1b9eecc8f4
1 changed files with 32 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
company/documentation/engineering/how-to-write-design-doc.mdx
View File

@@ -10,7 +10,7 @@ Writing a design document helps you efficiently solve broad, complex engineering
**Writing a design will help you:**
- **Understand the problem space:** Deeply understand the problem you’re solving to make sure it is well scoped.
- **Understand the problem space:** Deeply understand the problem you're solving to make sure it is well scoped.
- **Stay on the right path:** Without proper planning, you risk cycling between partial implementation and replanning, encountering roadblocks that force you back to square one. A solid plan minimizes wasted engineering hours.
- **An opportunity to collaborate:** Bring relevant engineers into the discussion to develop well-thought-out solutions and catch potential issues you might have overlooked.
- **Faster implementation:** A well-thought-out plan will help you catch roadblocks early and ship quickly because you know exactly what needs to get implemented.
@@ -32,17 +32,27 @@ Every feature/problem is unique, but your design docs should generally include t
2. **Overview**
- A high-level summary of the problem and proposed solution. Keep it brief (max 3 paragraphs).
3. **Context**
- Explain the problem’s background, why it’s important to solve now, and any constraints (e.g., technical, sales, or timeline-related). What do we get out of solving this problem? (needed to close a deal, scale, performance, etc.).
- Explain the problem's background, why it's important to solve now, and any constraints (e.g., technical, sales, or timeline-related). What do we get out of solving this problem? (needed to close a deal, scale, performance, etc.).
4. **Solution**
- Provide a big-picture explanation of the solution, followed by detailed technical architecture.
- Use diagrams/charts where needed.
- Write clearly so that another engineer could implement the solution in your absence.
- Break down the solution into meaningful, logical chunks that can be implemented independently. Consider:
- Core infrastructure vs feature-specific implementations
- Backend services that can be built and tested in isolation
- Data model changes that can be implemented in phases
- API endpoints that can be versioned and rolled out gradually
This breakdown will inform your milestones and help reviewers understand the implementation strategy. If you find yourself planning PRs that are 3,000+ lines long, it might be a sign that you need to break down the work further. While PR size isn't the primary factor in determining breakdown, it can be a useful indicator that a chunk of work might be too large to review effectively.
5. **Milestones**
- Break the project into phases with clear start and end dates estimates. Use a table or bullet points.
- Each milestone should align with the logical chunks identified in the Solution section.
6. **FAQ**
- Common questions or concerns someone might have while reading your document that can be quickly addressed.
## **How to Write a Design Doc**
- **Keep it Simple**: Use clear, simple language. Opt for short sentences, bullet points, and concrete examples over fluff writing.
@@ -51,14 +61,15 @@ Every feature/problem is unique, but your design docs should generally include t
Before sharing your design docs with others, review your design doc as if you were a teammate seeing it for the first time. Anticipate questions and address them.
## **Process from start to finish**
1. **Research/Discuss**
- Before you start writing, take some time to research and get a solid understanding of the problem space. Look into how other well-established companies are tackling similar challenges, if they are.
Talk through the problem and your initial solution with other engineers on the team—bounce ideas around and get their feedback. If you have ideas on how the system could if implemented in Infisical, would it effect any downstream features/systems, etc?
Once you’ve got a general direction, you might need to test a some theories. This is where quick proof of concepts (POCs) come in handy, but don’t get too caught up in the details. The goal of a POC is simply to validate a core idea or concept so you can get to the rest of your planning.
Once you've got a general direction, you might need to test a some theories. This is where quick proof of concepts (POCs) come in handy, but don't get too caught up in the details. The goal of a POC is simply to validate a core idea or concept so you can get to the rest of your planning.
2. **Write the Doc**
- Based on your research/discussions, write the design doc and include all relevant sections. Your goal is to come up with a convincing plan on why this is the correct why to solve the problem at hand.
3. **Assign Reviewers**