Table of Contents

This doc is a work in progress.

Honestly, it is not that difficult to make a design doc. It is difficult to make a design doc. Here I want to create a template for writing great design docs.

1. Title:

If you are designing for a major project from scratch you can name it as Project Name - Design

If you are designing a feature for a project you can call it: Project Name | Feature Name - Design

The title should be short and sweet and must include the 'Design' keyword to make it easily searchable in a repo of docs.

2. Authors:

Below the title you must mention/cite the authors of the Doc. Writing them in the priority of ownership is not a necessity but its a good thing.

3. Approvers:

Create a table having these columns: Name, Role, Approval Status. Role could have things like: Peer, Tech Lead, Architect, Product Owner and Engineering Manager. The Approval Status could be things like: Approved, Pending Review, In Progress, Changes Requested, Not Required, Rejected. It is better if it is a drop down.

4. Overview:

The Overview provides a high-level summary of the project or feature, giving context and setting the stage for the rest of the document. It outlines what the system or component is supposed to do, why it's being developed, and the broader context or goals.

5. Problem Statement:

The Problem Statement section focuses on the specific issue or challenge the project is addressing. It clearly articulates the problem that led to the need for the project or feature. This section helps explain why this solution is necessary and what pain points it will resolve.

A good section here will include:

1. Current Pain Points: Describe the issue(s) or limitations in the current system or process.
2. Impact: Explain the negative consequences if the problem isn't addressed.
3. Motivation for Change: Why this is a priority now (e.g., technical debt, inefficiencies, user needs).

The Overview gives a sense of "what" the project is about, while the Problem Statement focuses on "why" the project is necessary.

6. Goals:

The Goals section describes the specific objectives and outcomes the project is aiming to accomplish. It provides a clear and focused understanding of what the project will deliver.

A good section here will include:

1. Primary Objectives: Specific functionalities or improvements that the project will implement.
2. Success Criteria: What would be considered successful completion of the project? These could be metrics or qualitative results.
3. Expected Impact: What improvements or benefits will result from achieving these goals?
4. Alignment with Business/Technical Needs: How the goals contribute to overall business or technical objectives.

7. Non-Goals:

The Non-Goals section clarifies what is out of scope for the project. It ensures that readers understand the boundaries of the project, so there are no unrealistic expectations. It can also help avoid scope creep by defining what will not be addressed in the current project phase.

A good section here will include:

1. Explicitly Out of Scope: Specific features, functionalities, or aspects of the system that the project will not handle.
2. Limitations: Areas where the project will not attempt to make changes or improvements.
3. Future Work (if applicable): Sometimes non-goals may point to future work, but they are not part of the current project.