A Structured RFC Process by Phil Calçado

When I wrote Technical design: whether, who, how, and what it was partly because I haven't seen a lot of guides of this sort. I'm pleased to say that Phil Calçado has offered a similar how-to at A Structured RFC Process.

Some of the key similarities between A Structured RFC Process and my post are: (1) a discussion of who should be involved, what kinds of topics need this sort of process, what to include in such a design, and what it looks like to solicit and get feedback, (2) the focus is on the higher level or more important aspects, not specifying every detail, (3) the emphasis is on feedback and discussion, not on formal sign-offs, budgets, or other things which might be worth nailing down, but not in this sort of design, (4) relatedly, documents (and other artifacts like presentation slides or videos) produced during technical design have a relatively short half-life. They sometimes can be helpful well into the future but that's not their main purpose. Their main purpose is is to flesh out a change and organize writing code and whatever documents you have to describe "this is the current state of our system" (API documentation, wiki pages, or whatever you find useful). As Calçado says, "once an RFC moves away from Feedback requested, it is considered a historical artifact".

A few differences between my post and A Structured RFC Process are: (1) although I started thinking of a document with comments (as described in A Structured RFC Process), as I wrote I realized that most of what I was saying also applied to hallway conversations, presentations, or other modes of communication, (2) I include a list of technical issues you might want to address (or might not).

One interesting observation was "It is not uncommon for engineers to try and use the process as a way to sell an idea that hasn’t been approved by their stakeholders or managers" which I certainly have seen. Depending on how much of a power vacuum we are talking about (or, relatedly, lack of clear priorities), this could be a large or a small problem, but approaching design deliberately is not a substitute for making choices. It is at best a way to help clarify what choices the organization is facing.

And my favorite quote from the whole article is "The more polished a document looks, the softer and less impactful reviews tend to be". I love this. Not only does it match suggestions I've heard in other realms (for example, "to get good feedback on a user interface, show someone a napkin sketch, not a pixel-perfect mockup"), but it helps clarify one of the reasons why I've not always seen good results from highly formalized documents written in very structured and detailed ways. Not only is the content of such documents sometimes buried in a lot of boilerplate and irrelevance, but the very form discourages the kind of engagement which would make them seeds for raising issues which might be otherwise missed.