I think this is a great practice. We started doing this where I work at NewsCred like 6 months ago and it’s a lot easier to follow or give feedback on how something is being built. It greatly helps estimate work and de-risk unknowns. It also gives team members the opportunity to step up and take lead because there’s a clear process to research and prepare for the implementation of a project. Of course YMMV because if you’re crunched for time this process might get rushed and wrong decisions that would have been caught in the process end up making it into production. Or the opposite can happen and you can get stuck on a detail that blocks things from moving forward. But I haven’t found either to be the usual outcome.
Great to hear that you are using this practice!
I’ve been really surprised at how well it works - especially how well it works when doing it via a tool that supports super easy commenting like Google Docs or Office 365.
Yes, it takes some time to write what you plan to do down, but I see this almost like a validation step. If something is simple, it is quick to write it down. If it’s complex and takes a long time to explain what’s being done… well, that’s a smell!
Then, if the proposal is straightforward or no one leaves a comment, great! Either it means that’s it’s really not a big deal. Or if it was a big deal and people later complain, the option was there to discuss.
The trickiest part is what happens when you put together your simple or complex proposal and TONS of feedback comes back, slowing you down from building it. And you’re thinking “why do we have this process?” But taking a step back, if something is this controversial before starting coding - how controversial would have it been when deployed? Actually, this process might save a lot of time, forcing hard discussions upfront, rather than having to figure out how to drastically change code that was thought as complete, but a lot of other people/teams were unaware of it.
Where I work, we call them Architecture Reviews, and they’re sent out first as a doc to comment on, and sometimes accompanied by a presentation after people have had a chance to read. They’re usually just for new projects, but it would be interesting to do them for migrations, rewrites, etc.
My current place does something similar to this, we nicked it from Joyent, joyent/rfd. Also used them quite successfully in the operations team at the last place I worked.