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.).
   • Consider whether this feature has notable sales implications (e.g., affects pricing, customer commitments, go-to-market strategy, or competitive positioning) that would require Sales team input and approval.

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

5. Sales Approval (When Applicable)

   • If your design document has notable sales implications, get explicit approval from the Sales team before proceeding to implementation. This includes features that:
     • Affect pricing models or billing structures
     • Impact customer commitments or contractual obligations
     • Change core product functionality that's actively being sold
     • Introduce new capabilities that could affect competitive positioning
     • Modify user experience in ways that could impact customer acquisition or retention
   • Share the design document with the Sales team to ensure alignment between the proposed technical approach and sales strategy, pricing models, and market positioning.