Writing It Down
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.
