Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Design Document Template

Contact Info

List of project members and their contact information.


Tenets are a list of guiding principles for your project. Your tenets will keep you focused on your objective and keep you heading in the right direction.

Tenets are independent of each other, are clear and memorable. They are used to define what a team cares more about.

Tenets are used to to help make difficult choices and trade offs in design decisions.

Executive Summary

A high-level paragraph explaining the purpose of the document. This should be written with the scope that anyone in the company can view this document and have an understanding of the proposal. Include a summary of the problem, any background information and the proposed solution.

Measures of success

What will make this project successful? This can be listed as a bullet point list of key features, workflows, and qualitative metrics; such as increasing performance by X%. These measurements should not be considered pass/fail, but rather used in the retrospective to probe further questions into the system if needed.

In Scope

A list of things that you will do / address / solve as a bullet point list.

Out of Scope

A list of things that you will not do / no address / not solve as a bullet point list. Sometimes it is easier to start with this before writing what is In Scope.

Open issues

List of issues that you currently do not know how to solve. When having a design document review, these issues should be addressed and solutions proposed.

Use cases

Create an architecture diagram of your proposed system including any external systems that it will interact with. For more information on Use Cases visit the Wikipedia article.

Proposed solution summary

Write about how your solution works in a detailed narrative, refer to appendices for diagrams, APIs, data structures, database schemas, etc.

Other solutions

Describe any alternative solutions that you may have prototyped. Compare these alternative solutions to the proposed solution. List off the pros and cons of each solution, and why the proposed solution is the one you decided to go with.


List any external dependencies that your solution has, and why.

Functional requirements

A list of properties that can be expressed as “the system must do ”. The requirements should be measurable. Think of metrics. E.g.:

  • Users should be able to easily download prediction results.
  • The system should have a logically defined API.
  • The service should be able to handle 10,000 concurrent users.

Non-functional requirements

A list of properties that can be expressed as “the system shall be ”. E.g.:

  • The system shall be secure
  • Maintaining the system should be well defined and simple
  • The service should be easily extendible, its components should be modular.

Some categories which non-functional requirements can be placed in are:

  • Security
  • Extendability / Maintenance
  • Scalability
  • Availability / Resilience
  • Performance


Define metrics for both functional and non-functional properties of your solution.


Define your alarms based off of the metrics above.


Include things such as:

  • Glossary
  • FAQ
  • One pagers
  • API definitions
  • Database Schemas
  • Links to dependencies
  • External documentation

This comment has been minimized.

Copy link
Owner Author

@mattBrzezinski mattBrzezinski commented Jul 26, 2020

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment