Lessons I learned while implementing technical RFCs as a management tool | Hacker News Reader

Lessons I learned while implementing technical RFCs as a management tool

buriti.ca

102 pointszeisss40 comments

I'm convinced the most effective way to rally engineers under a common cause and a unified vision is not with individual tech specs, fuzzy PRDs and sprints of work, but with an RFC. Writing an RFC demonstrates that you have thought enough about a problem to devise a working solution that is not rash but also admittedly not perfect (unless it is). RFCs are so much more than technical prose. They're context and history and rationale and concensus all at once.

Unfortunately, many engineers and managers scoff at the idea of writing an RFC because of the traditionally poor UX instead preferring collaboration tools and diagrams. As a coworker once put it, "diagrams are weak sauce". Collaboration software is convenient for comments and visibility, but it fails to carry the same weight as an RFC and tends to produce more ephemeral artifacts. The best thing about writing an RFC is learning how people (mis)interpret your writing. If you want to win an engineer's heart, speak their language.

> Writing an RFC demonstrates that you have thought enough about a problem to devise a working solution that is not rash but also admittedly not perfect

This is critical. One of the most important parts of the RFC process is that by its very nature it invites comment. It specifically invites people to poke holes in it, to find issue with it, to voice their concerns and be heard. While it doesn't promise unanimity, it promises consensus. And while every single objection may not be fully satisfied, every one of them should be addressed.

An RFC averts the tendency towards an overabundance of confidence, warranted or otherwise, and instead starts a discussion.

I do also like the idea of dropping sprints in return for rfc bounded projects

Agreed that the way to rally is with specs... and distributing said specs (it's not enough to write the spec, it needs to get reviewed and communicated).

The big challenge is that developers tend to only think of "spec" as in "technical specs", whereas the most important specifications are the context, the goals and the history (the "function specs" in project management terms).

"include team members without it becoming design by committee"

This point is mentioned but there's no clarification. As soon as you open up a design discussion to other members you're heading to design by committee territory, unless you take specific action to control it. Is there something in the formalized RFC process that addresses this?

Someone once said to me that RFC stands for Request For Comments, not Request For Consensus.

It is an opportunity for you to get important feedback about aspects of the plan you might be under-informed about and make sure the relevant parties are aware of what is happening.

After feedback, you may decide your plan was flawed and needs adjustment, but just because there is disagreement doesn't mean you need to change your design to fit everyone's needs.

I do think consensus forms a critical part of the process. But consensus does not mean unanimity, and not every objection requires changing the plan to accommodate it.

An RFC should seek to articulate the key constraints, surface every unique point of disagreement, and address every one of those. Sometimes, addressing such a point may involve changing the proposal; other times, it'll involve providing a considered and thoughtful response that amounts to "no, and here's why not". That may lead to someone dropping the objection on further consideration, or refining their concerns in an effort to better articulate what they value that they feel the proposal doesn't deal with. And occasionally, even after that, the answer may remain "no", and the objection will stay on record as disagreement with the consensus.

RFC authors are not to incorporate all feedback into their proposals. they can choose to ignore all comments, it's utlimately them who will be responsible for system outcome of their technical proposal

Paging Howard Roark :-)

The idea of writing RFCs for intra-organization engineering doesn't jive with my experience of needing to hack out prototypes to come up with good solutions to problems. Writing a huge RFC before writing code seems to be something that should be the exception not the rule. How do you balance this?

For protocols or standards RFCs are a natural fit because they are about mutually agreed upon communications and formats -- its self evident they must be based on consensus since the consensus itself is the core of what delivers value. Many software development tasks (including examples given by the author) do not have the characteristic of necessitating consensus so requiring RFCs seems to be a trade-off between consensus and other important things like velocity or iteration cycles, not essential complexity to solving the problem.

I wouldn't think that an RFC would have to come before hacking out a prototype. In fact, doing a prototype is probably a great way of preparing for writing an RFC.

And vice-versa - in fact, I'd put a lot of faith in a prototype accompanied by an RFC. I think each would help to materialise the other.

I think the author is using RFC not to strictly mean, "IEEE Standards Doc" but more, "a description of the problem you're solving and why also open for comments". I guess in my experience shipping code gung-ho is great for about a year maybe two and then you really start getting to a point where every engineer just cakes their own great ideas on without a technical blueprint of what the company is actually building. Maybe that can be addressed by better technical management, but also in my experience technical managers are not great at conveying overall architecture and context (and perhaps it's not really their fault if non exists in the first place--but that's exactly the problem). I agree you're making a trade off but I don't think it has to be as hardcore as a 20 page specification for IPv10. A small startup with a few engineers can share contex and vision just fine.. until they can't. And the big win with RFCs is you put tribal knowledge down on paper up front instead of post facto.

I think the main point I'm trying to make is that RFCs are a way to capture technical intent not just product requirements. It's not enough to just keep adding features whenever product asks for them (which is always and in a volume that's more than than you have time to do). You shouldn't have to get to the point where the thing or the business is going to fall over to get engineers to agree to build responsible software or refactor that shitty thing to actually work properly. I think RFCs help frame building software in an engineering-driven-but-product-inspired-and-business-context-aware way. That's how I want to work, anyway, but what you get with product-driven sprints is product-gets-their-way-and-business-context-is-solved-with-more-funding-for-that-aws-bill-and-for-more-eng-resources-to-build-more-product-value-so-you-can-charge-more-for-the-product.

Prototypes and RFC can go hand in hand or RFC can be later in the process. I don't think it's either/or choice. The example problem author gives is that someone built something but hasn't communicated across the team. As he points out the list of issues, consensus is the least (3rd - "Someone made an important decision on behalf of our entire team, but the team wasn’t included in it") of the worries. As someone pointed out in the thread it is "Request for Comments" and not consensus. It is fine even if comments are ignored by the author.

It is never fun having to find out something has changed only after production release or later down the line.

An RFC doesn't have to be huge. Even one that becomes huge doesn't have to start that way, and probably won't. As the article points out, intra-organisation work isn't the kicker here in itself - inter-department work is where the concept has merit.

I think this is an awesome idea (and I believe Amazon has something similar - powerpoints are banned and proposals must be written)

Formalising that into something like a RFC / PEP seems a great idea. Add in the email based discussions and it's the start of bringing democracy into the feudal corporate world

Why email?

Its the OG social network and has better everything (search,history etc) than anything else out there. I hate using skype/slack/etc for comms, better to just use a phone or write an email.

This

I'm struggling to understand the intended meaning of this comment "In addition, when there is a document they can refer to, individual contributors (ICs) can be given concrete feedback on performance if important decisions which are part of their responsibilities were not on their radar." Can anyone help interpret it?

Assuming the author is reading this, how do you manage the feedback and decision-making process for these RFCs?

The way the author uses "RFC" is that it's essentially a possibly very rough draft design document for some technical implementation. The "Comments" part is what is otherwise known as a "design review."

My opinion is that what to do with feedback and final decision authority rests with the proposal owner except under certain circumstances. Some of these would be if a component of the proposal is particularly complicated, clearly not completely understood by the team (e.g. there are dependencies on other teams that need more clarity), or contentious (e.g. major rewrites, switching to new frameworks or data storage and pipelines, etc.). In the latter I require consensus especially: proliferation of languages, data store solutions, and frameworks is a real problem and rarely a good solution.

I assume the author meant that there is a paper trail (similar to commit history or bug tracking) that can be reviewed at performance time to evaluate if an IC was paying attention to and contributing to the design process.

I want to work in a place that uses this process I really do. Feel free to contact me if you are looking for employees and use this process.

One obvious response: Can you (help) make it happen where you are?

I am currently very close to finishing my studies, so I cannot.

In my job, we create GitHub Issues labeled "Discuss", which are essentially requests for comment. It's a great way to outline a problem you want to solve, test your assumptions, gather thoughts from the team, and create transparency. For the ideas which are really ground-shaking, we send an email to the team with a link to the Issue with a brief synopsis.

This has been food for thought for me. I'm currently part of an engineering team that's a small part of a non-engineering department, with all the disjuncture between management and coal-face workers that situation always brings, and then some. I think I may be proposing something RFC based on Monday.

This article really bothered me. "An important decision had been made on behalf of the team."

Their solution to that was to make everything in the company revolve around the manager. After feeling personally hurt that they weren't included on every decision ever, now there's paperwork which can HOLD PEOPLE ACCOUNTABLE if they break "the documented rules".

Those darn workers better check those rules every time they're about to do something just in case, and if it's a new thing, ho boy, they better think twice because now they have to be prepared to wade through all that argumentation and red tape first.

This is awful and borderline mentally ill. It instills a fear culture into employees and ignores that developers want to write code. Instead it's trying to force them into the manager box of talking big and shouting each other down until an idea wins. Sick.

You know what the solution was? "Yeah, well they built it and it's pretty cool. If you want to do it in something else then make a better one." End of problem.

If this person was my manager I would be looking for a new job.

An RFC does not have to be hostile, or a debate. In it's simplest form you're explaining the changes you're about to make and gathering input. There is absolutely no fear here. It sounds like you're projecting a previous toxic environment onto this subject.

A team where everyone is doing things "their way", and then rebuilding it if it wasn't up to par is an enormous waste of resources.

This is over-the-top negative. An RFC is not intended to be "paperwork", about the manager, or about "shouting each other down until an idea wins" - it's way more about the engineer, and helping us create a good design that has broad buy-in.

Specifically, writing RFCs asks an engineer to articulate a design, consider and list the tradeoffs involved, and evaluate it against a set of motivating use cases. It also invites feedback: other people may have legitimate concerns or find blind spots. As the writer you don't have to make changes to incorporate everyone's views: it's up to you to decide on a case-by-case basis if their feedback needs to be incorporated or not.

I think there is a middle ground between cowboy developers just doing whatever they want and a tyrannical, cumbersome and hostile design process.

RFCs point both ways. Documenting decisions is a positive management trait. Otherwise you can easily end up with a mess that no one takes responsibility for.

Management decisions and associated rules will happen regardless of documentation. It is better to have a paper trail.

> If you want to do it in something else then make a better one. And what is the end result of that? The old code gets deleted, and the person that implemented it might get angry because it sucks to spend time on something only to have it deleted. How is that better?

The NPM team also wrote something last year about their internal use of RFCs: http://blog.npmjs.org/post/153881413635/some-notes-on-rfcs

I don't understand what he thinks an RFC is in this context? Is he basically just saying that it's an architecture document and he gets feedback from developers? Does everyone not already so that?

No - everyone very definitely does not already do that :-) in fact this is something I have pushed to some degree or other at every place I have worked and only where I had CTO level authority did I get it taken up

Count yourself lucky if it's common for you :-)

So I guess Working Software more than comprehensive documentation is officially out, now? Well it had a long run than most ideas we have.

I think there is a difference between documentation for yourself(and your team) and others.

I think documentation for others (your users) is still needed, but I rarely write documentation for myself or my team.

Sounds like a lot of red tapes.

We've also moved to an RFC process in our group of 80 (~50 developers.)

Reply on news.ycombinator.com