3 ms·

It's very interesting to read this. I've come around to the exact same ideas, with the same perspective, and for the same reasons you've listed here. I've also

It's very interesting to read this. I've come around to the exact same ideas, with the same perspective, and for the same reasons you've listed here. I've also had the same experience. These docs are critical for my team at this point. Without them, we'd go back to languishing for any number of weeks while we grapple to understand the larger context. All of that said, it takes me at least 2x longer to get these documents created. It's easily a 1-2 day affair for me. I'm also on a small team, with only 4 engineers, and the projects we work on tend to run 1-3 months. I wonder if this process scales to larger teams and projects.

grogenaut 8y ago
It used to take me that long. For more detailed docs it still does. I'm also way slower when it comes to business justification and executive team arguments but getting better. Practice makes perfect though. 5 years ago it would take me multiple months to write such a doc and I'd get bored constantly. Now I'm much faster. Some of my mentors can do these things on the fly in a meeting and drive consensus easily on stuff they have 0 context on. I also got better because I had a manager who suggested that I just start writing these things up for a few hours each week. Just like authors who say that you have to write to get better at it, and how you write essays in high school and college even for arguments you don't believe in. As for scale the process, yes it seems to. We try to review anything that's 3 months engineer time or more with a Sr. engineer from another team. Wider for larger projects. Bring in Principals when you have real quandaries. The trade off is really writing time to communication effectiveness. If you find yourself having the same slack discussion more than 2x, maybe it should be in a document.

3 ms·

It's very interesting to read this. I've come around to the exact same ideas, with the same perspective, and for the same reasons you've listed here. I've also

by scruple 8y ago

grogenaut 8y ago
It used to take me that long. For more detailed docs it still does. I'm also way slower when it comes to business justification and executive team arguments but getting better. Practice makes perfect though. 5 years ago it would take me multiple months to write such a doc and I'd get bored constantly. Now I'm much faster. Some of my mentors can do these things on the fly in a meeting and drive consensus easily on stuff they have 0 context on. I also got better because I had a manager who suggested that I just start writing these things up for a few hours each week. Just like authors who say that you have to write to get better at it, and how you write essays in high school and college even for arguments you don't believe in. As for scale the process, yes it seems to. We try to review anything that's 3 months engineer time or more with a Sr. engineer from another team. Wider for larger projects. Bring in Principals when you have real quandaries. The trade off is really writing time to communication effectiveness. If you find yourself having the same slack discussion more than 2x, maybe it should be in a document.