3 ms·

This sounds like a description of a Design Document, which are very valuable when the problem space is well understood. It can serve as an alternative to sprin

This sounds like a description of a Design Document, which are very valuable when the problem space is well understood. It can serve as an alternative to sprints and sprint planning for a very small team, or when working with contractors. When a problem is not as well understood, e.g. can't be solved just by engineering planning upfront and needs user input, I like Google's Design Sprints which uncover the critical features using a 1 week process. With my experience leading engineering teams and growing startups, I agree completely that documentation is the #1 blocker in scaling engineering teams, all else being equal. If the design, planning, and execution process are well-documented then engineers can be onboarded as soon as they are hired without slowing down the team too much.

prepend 8y ago
I think this has a similar purpose as a design document. But the examples they show for the RFCs are more tactical. And are distributed broadly across their company. Design docs get a bad rap for “big design up front” because, I think, they get fetishized as risk management rather than accomplishing their functional task. For this post, I think the best part is being able to gather good review and edits, and track changes as decisions are made and why.
jononor 8y ago
Adding to that, I often find that trying to write documentation (spec or otherwise) tends to help reveal which things lack clarity or understanding. In this way it can be useful also in unknown territory.
derefr 8y ago
To me, a design document is something you write for yourself, once you’ve decided on the design; whereas an RFC is something you write for others, and others write for you, to communicate a potential design when a final design hasn’t yet been “selected.” It’s effectively a way of brainstorming that doesn’t get quashed by “that’ll never work” half-way through the 1000-ft abstract, because all the details are already there on the page to prove it will work. It’s just a question of which of the proposed designs works best (and then of attempting to maybe incorporate some of the alternatives’ ideas into the winner, though not necessarily.) Or, in short: it’s a debate where everyone is doing an “argument by constructive proof” for their POV. The cryptographic-primitive standardization “competitions” for things like SHA, are RFC processes under another name.

prepend 8y ago

I think this has a similar purpose as a design document. But the examples they show for the RFCs are more tactical. And are distributed broadly across their company. Design docs get a bad rap for “big design up front” because, I think, they get fetishized as risk management rather than accomplishing their functional task. For this post, I think the best part is being able to gather good review and edits, and track changes as decisions are made and why.

jononor 8y ago

Adding to that, I often find that trying to write documentation (spec or otherwise) tends to help reveal which things lack clarity or understanding. In this way it can be useful also in unknown territory.

derefr 8y ago

To me, a design document is something you write for yourself, once you’ve decided on the design; whereas an RFC is something you write for others, and others write for you, to communicate a potential design when a final design hasn’t yet been “selected.” It’s effectively a way of brainstorming that doesn’t get quashed by “that’ll never work” half-way through the 1000-ft abstract, because all the details are already there on the page to prove it will work. It’s just a question of which of the proposed designs works best (and then of attempting to maybe incorporate some of the alternatives’ ideas into the winner, though not necessarily.) Or, in short: it’s a debate where everyone is doing an “argument by constructive proof” for their POV. The cryptographic-primitive standardization “competitions” for things like SHA, are RFC processes under another name.