A Brief Literature Survey on RFCs and Design Document Workflows

In an attempt to build a scalable mechanism for cross-team decision making, I have done some research on what appears to be the industry standard for coordinating this kind of process - the Request for Comments / Design Document workflow.

The names of the processes appear to vary wildly, but typically revolve either around the idea of a "proposal" for which feedback is solicited, or the idea of a "decision" which is agreed upon after review.

Important features of the workflow include:

• a clear definition of the problem being solved
• background and context on why the problem needs to be solved
• traceability: being able to determine when a decision was made, and who contributed to making that decision
• enumeration of pros/cons and alternatives: understanding the decisions that were not made is just as important
• standardised components for commonly overlooked concerns, such as security and cross-team concerns: avoids any awkward and repetitive "did you consider this?" questions that would happen at the start of each proposal
• implementation details
• a clear process for making new decisions: a proposal should never be in an ambiguous state (ambiguity kills productivity and diffuses responsibility)
• clear distribution of responsibility: "who ensures the process is not blocked" and "who is needed to sign off"

It appears to be tradition that the first such document submitted by this procedure is a document that formalises the process of design documents or the like.

Literature review

Python Enhancement Proposal

The original PEP: https://www.python.org/dev/peps/pep-0001/#pep-formats-and-templates

This is a very standardised format, both with an ordering and a template that needs to be followed. Since the PEPs are intended to partially function as documentation, it includes sections such as "How to Teach This", which I quite enjoy.

Architectural Decision Records

A blog post about this: https://multithreaded.stitchfix.com/blog/2020/12/07/remote-decision-making/

• problem context
• history
• ideal future state
• alternatives
• decision
• example
• follow-up actions, consequences (w.r.t. implementing this decision)

Stripe style

A presentation about this, from a software architecture point of view: https://noidea.dog/maybe-great/

• goal
• dependencies (what does this affect?)
• prior arts
• operational impacts
• security
• risks
• detailed design

Important to have: who read it + what is expected of each reviewer

Google style ("bluedoc")

Example: https://mirrors.edge.kernel.org/pub/software/scm/git/docs/technical/hash-function-transition.html

• objective
• context
• goals and non-goals
• overview
• detailed design
• alternatives considered
• other considerations (operations, security) (at Google they have separate security and privacy reviews, which makes this slightly less prominent)
• plan

See also: https://bazel.build/designs/index.html

Bibliography

• https://staffeng.com/guides/engineering-strategy
• https://multithreaded.stitchfix.com/blog/2020/12/07/remote-decision-making/
• https://noidea.dog/blog/design-documents
• https://noidea.dog/maybe-great/
• https://www.industrialempathy.com/posts/design-docs-at-google/