Oxide
Oxide has very interesting Requests for Discussion which seem just right.
Before starting a project, one originally wrote an informal document defining the design, documenting:
- implementation strategy (in terms of problem solving, not code!)
- key design decisions (esp. trade offs considered)
Structure not strict, but can include:
- context and scope
- goals, non-goals - what you want it to do, what you explicitly aren’t trying to do (e.g. don’t care about ACID)
- the design
- system context diagram - shows the system in the overall technical landscape (e.g. what services it context to)
- API, data storage - if it exposes an API, sketch it. Not formal definitions, but parts relevant to the design and trade offs
- constraints
- alternatives considered - which could achieve similar outcomes, focusing on tradeoffs informing the decision
- cross-cutting concerns - security, privacy, observability…
Endeavor to challenge and share the doc, getting input until it’s stable. Then rapidly iterate the doc while implementing, noting what worked or failed, shortcomings, unaddressed requirements etc.
Edited 7.5.24 in light of https://news.ycombinator.com/item?id=40273534 : the promotion ecosystem at Google has long since become toxic, with overwrought design docs microoptimizing for promotion (along with the products they describe.) Nevertheless, keeping a good .md in a repo explaining the thought process actually used is useful. (Issues appear when you performatively add irrelevant or fake details.)
Amazon
Six-pager and PR/FAQ formats
Amazon uses writing to bias for action in meetings. Their culture has DRIs (or dictators) who have authority to make the call, with such authority coming with some level of accountability to the decision made. At Amazon the doc is read, parties discuss, and decision made. At Google the doc is rarely entirely read, mostly commented on, and no decision made until all stakeholders align on a commonly agreed direction.
The amazon way is much less toxic, but does come with a need for writer to invest heavily on a high quality doc. Personally, the Amazon way is better but only works due to their peculiar culture.
From: https://justingarrison.com/blog/2021-03-15-the-document-culture-of-amazon/
A majority of my meetings start with reading a document. This takes “this meeting could have been…” and flips it upside down. If there isn’t a doc there isn’t a meeting. Depending on the task, the document could be a six-pager, a PR/FAQ, a one-pager about an idea, a narrative to help find a solution to a problem, or even a service review full of charts, graphs and bullet points.
Reading documents is so ingrained in our culture and process that our scheduling tools have check boxes to automatically create a document. If I’m catching up on a new service or feature launch, I will find the document rather than emailing or calling the product manager.
The interesting part to me isn’t in the format of the document, but how it is used. Meetings start with reading. Depending on the length of the document, we’ll read anywhere from ten minutes to half an hour. If the meeting has a long document (six-pagers are the longest) and many attendees, the meeting will be scheduled for enough time to read and discuss.
Reading the doc is part of the scheduled time. You are not expected to retain document information outside of the meeting.
The discussions in meetings enable faster feedback loops, but the downside is they can limit the potential for asynchronous engagements if notes and questions aren’t captured in the document.