How to write a design document

​

Why write a design document?

Writing a design document helps you efficiently solve broad, complex engineering problems at Infisical. While planning is important, we are a startup, so speed and urgency should be your top of mind. Keep the process lightweight and time boxed so that we can get the most out of it.

Writing a design will help you:

• 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.

When to write a design document:

• Write a design doc: If the feature is not well defined, high-security, or will take more than 1 full engineering week to build.
• Skip the design doc: For small, straightforward features that can be built quickly with informal discussions.

If you are unsure when to create a design doc, chat with @maidul.

​

What to Include in your Design Document

Every feature/problem is unique, but your design docs should generally include the following sections. If you need to include additional sections, feel free to do so.

1. Title
   • A descriptive title.
   • Name of document owner and name of reviewer(s).
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.).
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.
5. Milestones
   • Break the project into phases with clear start and end dates estimates. Use a table or bullet points.
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.
• Use Visuals: Add diagrams and charts for clarity to convey your ideas.
• Make it Self-Explanatory: Ensure that anyone reading the document can understand and implement the plan without needing additional context.

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.

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
   • Ask a relevant engineer(s) to review your document. Their role is to identify blind spots, challenge assumptions, and ensure everything is clear. Once you and the reviewer are on the same page on the approach, update the document with any missing details they brought up.
4. Team Review and Feedback
   • Invite the relevant engineers to a design doc review meeting and give them 10-15 minutes to read through the document. After everyone has had a chance to review it, open the floor up for discussion. Address any feedback or concerns raised during this meeting. If significant points were overlooked during your initial planning, you may need to revisit the drawing board. Your goal is to think about the feature holistically and minimize the need for drastic changes to your design doc later on.