1. 39

  2. 14

    Generating RFCs are incredibly useful in my current employment. I belong to a remote first company and my team is distributed over a few timezones. I find it useful to quickly generate a document on each problem I work on. This gives my peers a chance to stop me before I go down a wrong path, helps solidify my understanding of the problem, and helps share knowledge with others. I think the fact that my current job is fully remote contributes largely towards me building this habit. At my last job, I could roll over a whiteboard over to my coworker’s desk and hash something out in real time - and often I wasn’t interrupting him because he was watching smash twitch streams. Now people are a lot more busy, have different schedules, so that asynchronicity helps.

    At the end of a life cycle of one of these documents, we generate a decision document. This contains a particular decision and alternatives considered alongside their pros + cons. It’s useful for when people ask questions about why we went down a particular path - we can quickly refer them to that document. It helps curb brady bunch type conversations when we don’t need them.

    We also have a coalition of principle engineers that will review more comprehensive RFC documents that change a rather large part of our system. Each one of those engineers works in different domains, so they can raise their concerns and provide helpful alternatives with large efforts that have future consequences on our system architecture.

    1. 9

      I’m writing a lot of such documents at work. We call them Design Decision Documents (DDDs). I have two minor suggestions, which I learned:

      Have a clear status at the top. Is it still a draft? Decided? Or maybe obsolete? It gets a colored background in red or green to make it obvious.

      Reference a ticket for the implementation. It often takes a while to actually change everything once the decision is made. I often got questions if the system now actually works like the DDD describes it or if we are still working on it. This question is quickly and asynchronously resolved if you can just look at some ticket status.

      1. 8

        I’m really not a big fan of RFCs in the workplace for most things, mostly because:

        • I prefer to have the discussion in the ticketing system or issue tracker–singe source of truth or many sources of lies and all that.
        • RFCs without accompanying implementation details can frequently be really loosy-goosey and not that useful.
        • Engineers will happily pad RFCs with other options that they aren’t seriously considering, giving fake rigor to them.
        • Management or senior engineers may just do an RFC and then say “okay, here’s what we’re doing instead” without actually following the recs of the RFC–or using it as just pro forma for what they were going to do anyways.
        • It can result in quality bikeshedding, especially if the document is open to a large peanut gallery.

        There’s another issue I have, somewhat brought up by the author:

        After I write the first draft I circulate it among a small group of peers I respect, my boss, etc. I request feedback at leisure and I check in every few days with a reminder. If no one responds after a while and there is little concern, I typically move forward with the proposed solution.

        “Every few days” implies a latency of decisionmaking on the order of a week or two. My experience has been either that people follow the RFC process and take way too long to converge to a solution, or that the people implementing it ignore the RFC. Both usually have knock-on effects.

        I think it’s a neat idea in theory, but I haven’t seen much beenfit from it on the teams where we’ve used it.

        1. 4

          All of these can definitely be issues. There’s still often value in going through the exercise of specifying solutions and listing alternatives/objections, and of capturing explicitly what decisions were made.

        2. 4

          I use something like this called a PDR (Problem, Diagnosis, Remedy) format proposal. I wrote up a template here: https://github.com/colindean/problem-diagnosis-remedy-proposal

          I’ve used this probably dozens of times in the last 10 years since the CEO of my then-employer taught it to me as a way of focusing my enthusiasm for the endless possibilities I saw for our improvements to our product and ways we could use it as a basis for more products.

          1. 3

            This follows Lamport’s classic state the problem before describing the solution advice.

            1. 2

              I love the quote at the bottom:

              (I am ignoring as unworthy of consideration the disturbingly large number of papers that never even attempt a precise statement of what problem they are solving.)

          2. 1

            I have been doing this for the past couple years using the Architecture Decision Record format. I’ve never regretting spending time writing one.