[frfl]

> Writing Mediocre Architecture Documents

Would you be willing to share this slide deck?

My question in regard to this is how do you write an architectural doc if you're exploring the problem space? If it takes 5h to explore, experiment and find the solution. And it takes 0.5h to write the doc. And 0.5h to make the change after you know the solution and have reverted the experimental/exploratory changes?

At that point is the doc necessary as a precursor to the change. By that I mean, do you send it out for feedback first and wait OR do you send it out/add that as a comment on you PR and push up the final change?

Additionally how do you know you're going to get feedback at all from sending out the doc? In my experience people are always busy with their own work and sending them a big chunk of text...well I wouldn't expect a response quickly compared to a short 1-2 line question

[sgtnoodle]

I consider any code that's written to be "speculative" until its design has been vetted by another engineer. By speculative, I mean that there's no expectation that the code will be approved and merged in its present form. An architecture document is simply a good way to get that buy-in. If I write down what I plan on doing in a document, and then solicit feedback on it from a coworker, there's a very good chance that the same coworker will approve the resulting code without anything but bug and style fixes. If you're exploring the problem space, yeah of course go ahead and hack away at some code. If the experiments go exceedingly well and you end up with production quality code, go ahead and throw it in a PR for review. You have to be receptive to "bike shedding" feedback, though, since the PR is the first opportunity you gave for folk to give that type of feedback.

It's also perfectly reasonable to write and distribute a document that effectively says, "I have no idea what the requirements are, but I have an arbitrary idea for how we should proceed anyway." More often than not, your coworkers will help flesh out the requirements, or agree with your arbitrary design decisions. Either way, it's a lot easier to have that type of discussion on a free-form wiki page rather than in a github PR that you already spent 4 hours getting to compile and pass test suites.

Re: soliciting feedback, even verbose architecture documents tend to be relatively easy for your coworkers to digest. It is communication written for human consumption rather than machine consumption, after all. For one thing, you can have a lot of fun with them. One of my recent arch documents had at least a dozen MC Hammer puns in it. I had no trouble getting anyone to read through that. Also, if you give your coworkers the opportunity and they don't follow up on it, it does give you the high road in any eventual PR contention. "I mentioned this a week ago and asked you for feedback on it, why are you making a fuss about it now?" Not that you should be setting up your coworkers like that. You should make a good faith effort to solicit feedback, and keep politely pestering folk until they get to it. Until you get buy-in, any code written is still speculative, even if you tried your best and your coworkers let you down.

It helps to lead by example. If you prioritize giving feedback to coworkers over your own implementation work (reading their documents, doing their code reviews in a timely way, etc.), then your coworkers will tend to notice and reciprocate.

[frfl]

That's very insightful. Appreciate the write up. Thank you.

I noticed the slide deck stuff in a sibling comment, +1