News for hackers. Stuff that matters.
Re:Design Docs at Google by billfruit on Tuesday May 07, 2024 @03:13AM (#40283166)
Can we see some real documents? It is as if software design process documents are the closest guarded secrets, because I have never seen a real document being available for case study.
Re:Design Docs at Google by faizshah on Tuesday May 07, 2024 @03:29AM (#40283229)
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.
Re:Design Docs at Google by rullelito on Tuesday May 07, 2024 @03:23AM (#40283208)
Companies keeping their IP a secret? Weird..
Re:Design Docs at Google by Nexialist on Tuesday May 07, 2024 @06:36AM (#40284067)
The closest I have seen are the Oxide computer company RFD documents, many of which are public.

Example: https://rfd.shared.oxide.computer/rfd/0177

Main index: https://rfd.shared.oxide.computer

Re:Design Docs at Google by esafak on Tuesday May 07, 2024 @08:26PM (#40293077)
This is an awesome format, esp. the diagrams. I am glad to see the tools are public: https://github.com/oxidecomputer/rfd-site
Re:Design Docs at Google by swah on Tuesday May 07, 2024 @09:32AM (#40285234)
I guess in the open source side we would talk about Github projects with the greatest READMEs...