News for hackers. Stuff that matters.
Re:Design Docs at Google by iainmerrick on Tuesday May 07, 2024 @05:46AM (#40283839)
Thanks for these links!

I picked out one at random just to check if my skeptical reaction is fair: https://github.com/kubernetes/enhancements/tree/master/keps/...

- OK, this is actually a really good and useful doc!

- However, it's not an up-front design doc, it has clearly been written after the bulk of the work has been done, to explain and justify rolling out a big change. (See the "implementation history" timeline: https://github.com/kubernetes/enhancements/tree/master/keps/...)

- It looks like the template wasn't very useful; most of the required sections are marked "N/A", and there are comments like The best test for work like this is, more or less, "did it work?"

Re:Design Docs at Google by jppittma on Tuesday May 07, 2024 @06:58AM (#40284167)
Google is a huge company with ~180,000 employees. Sometimes people do sensible things.
Re:Design Docs at Google by iainmerrick on Tuesday May 07, 2024 @08:23AM (#40284629)
Well, sure! They have many thousands of really smart developers.

I don’t think this particular doc, although it is a really good doc, supports the design doc process as described in the original article. It looks like good work being done in spite of the process, not because of it. It’s obviously just one data point, but I’d put it down as a negative point.

I wonder if anyone has done a proper investigation into whether the process is a good one?

Re:Design Docs at Google by pjmorris on Tuesday May 07, 2024 @08:54AM (#40284878)
> However, it's not an up-front design doc, it has clearly been written after the bulk of the work has been done, to explain and justify rolling out a big change.

Shades of Parnas! [0]

[0] 'A Rational Design Process: How and Why to Fake It', Parnas, Clements, https://users.ece.utexas.edu/~perry/education/SE-Intro/fakei...

Re:Design Docs at Google by iainmerrick on Tuesday May 07, 2024 @08:38PM (#40293166)
Huh, I don’t recall reading this paper before, but it’s terrific! I hadn’t previously seen it laid out as clearly as this, but yes, “faking” the design doc is exactly what happens in practice, and it’s a good thing! Since we want design docs that are useful now, not just obsolete historical artifacts.