Why Write a Design Document?
The goal of the design document is to:
- Define the problem you’re trying to solve.
- Propose a solution, and explore alternatives.
- Instigate discussion on the issue.
- Arrive at a final conclusion on design.
- Archive design documents for future use.
It may be necessary to iterate on the design document several times before a final conclusion is reached.
How to Write a Design Document
There is no single format for a design document, but it’s common to include:
- Definition of problem
- Possible solutions
- Opinion on best solution
- Details on how the solution should be implemented.
Some useful tools for writing design documents are:
- Markdown: A syntax for writing well-formatted text-based documents.
- asciiflow.com: A webpage to draw flow charts using ASCII. This is useful for design docs written in text formats such as markdown.
- Markdown Reader: A Chrome extension that lets you view markdown (.md) files in Chrome. Once viewed in Chrome, the markdown file can be printed on a Mac simply by printing the page, and selecting “Save as PDF” as the printer.
- TLA/TLA+: A formal specification language for writing high-level specifications of concurrent and distributed systems.
- Pandoc: A tool for converting various text formats into one another. Pandoc supports converting Markdown to PDF, among others.