RFCs are critical. None of us know everything about every system, deeply understand all of the customer use
cases, or can anticipate what some other group is working on. An RFC gets your ideas and plans down in a
shareable and discussable format. It's about documenting a specific solution to a problem and gives others
insight into what you're doing, why you're doing it, and how it might impact them. It lets others use their
experience and point of view to help avoid problems in the future. This is critical to what we do and we should
not only do more of, we should do more to at least be aware of everyone else's RFCs, commenting and questioning
where appropriate. You can think of an RFC as a mission statement for a team/project.
But today's entry isn't about RFCs. It's about what comes
before the RFC. The problem with RFCs is that they're largely static and
represent the thinking at the beginning of the implementation cycle. Why are you writing that RFC anyway (hint:
it's not because you need to check a box for next year's promo packet)? Whether you call them
Filememos,
Architectural
Decision Records, RFPs, Vision
Documents, or something else entirely, you write them to answer that question.
Writing the vision doc means understanding the problem you're solving, getting agreement on the required use
cases, and documenting the goals and why those are the goals. It's about
providing context for the next person (and sometimes that person is future you) who needs to care so they are
working to the same goals and can make a choice compatible with those goals.
Development takes time. Existing use cases get changed and new ones get added. New people join the team.
Multiple decisions get made every day. part of making those decisions is how things fit into the detailed design
as put forth in the RFC. Equally important to those decisions is the business
problem we're trying to solve. Vision docs describe the end state we want so those decisions, regardless of who
makes them, are all in service of the same end state.
It doesn't matter if you're architecting a whole new self-driving vehicle, building an entire ML pipeline, or
adding an endpoint to an
existing service, you won't be working alone. For something the size of self-driving vehicle you need to
understand the problem
you're solving and make sure you, your co-developers, and especially your customers understand the problem
you're trying to solve. Features are great. You solve problems with features, but your customers don't buy features. They buy
solutions to problems (use cases). A vision doc keeps those solutions in the forefront at all times.
