Design Documents
When making larger changes to Samza, or working on a project, please write a design document. All of Samza’s existing design documents can be found here.
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
Design documents should be attached to the JIRA for the feature that the design is for. The JIRA should be labeled with the “design” label.
There is no single format for a design document, but it’s common to include:
- Introduction
- Definition of problem
- Possible solutions
- Opinion on best solution
- Details on how the solution should be implemented.
An example of a design document can be seen on SAMZA-402, which contains several versions of both the raw Markdown file and the PDF for the design document.
Tools
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.