Design Document
a overall design document for the project, inspired from the template google uses internally. use this document for a quick TLDR.
Context and scope:
a very general overview of what is actually being built or worked on. This section is to bring anyone up to speed on a certain objective. Keep it concise and clean.
Goals and non-goals:
a list of goals/outcomes that explicitly mentions what is to be done and what can be worked on in the future. It helps focus on the MVP and helps separate features that aren’t needed right now.
Learnings and Progress:
NOTE: prototyping itself is part of the design doc creation. “I tried it out and it works” is one of the best arguments for choosing a design.
start with an overview and then dive deep into details. Given the context (facts), goals, and non-goals (requirements), this is where we talk about problems faced and note down the solutions and show why a particular solution best satisfies those goals.
We will also write about what has been implemented and save any valuable references in case we have to come back and debug something. We give the reader a view of the larger technical landscape and contextualize what’s happening at each step of the way.
Alternatives considered:
This section lists alternatives that would have reasonably achieved similar outcomes. The focus should be on the trade-offs that each respective design makes and how those trade-offs led to the decision to select the design that is the primary topic of the document.
Be succinct about the solution that ended up not being selected, and explicitly state why the selected solution is the best given the project goals and how other solutions, that the reader may be wondering about, introduce trade-offs that are less desirable given the goals.
Cross-cutting concerns:
a relatively short section that explains problems faced during implementation and future problems that can occur because of the proposed design.
Review & Suggestions:
This place is exclusively for Prof. KC Sivaramakrishnan and the Jane Street Folks (Hi Andy and Nigito !) to their thoughts and discuss the scope of improvement. It's just excess overhead to have a meeting every week so we can save the meets for actually important things to discuss and save time by working on this shared doc.
This leads to an eventual state more akin to the US Constitution with a bunch of amendments rather than one consistent piece of documentation that is left to be deprecated. Such amendments from the original doc can be immensely helpful for the poor future maintenance programmer trying to understand their target system through design doc archaeology.
Last updated