4 ms·

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 a

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.

rullelito 2y ago
Companies keeping their IP a secret? Weird..
faizshah 2y ago
Chromium: https://www.chromium.org/developers/design-documents/ https://www.chromium.org/developers/design-documents/ Kubernetes: https://github.com/kubernetes/enhancements/tree/master/keps https://github.com/kubernetes/enhancements/tree/master/keps
- iainmerrick 2y ago
  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/sig-architecture/4402-go-workspaces 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/sig-architecture/4402-go-workspaces#implementation-history 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?"
  - jppittma 2y ago
    Google is a huge company with ~180,000 employees. Sometimes people do sensible things.
    - iainmerrick 2y ago
      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?
  - pjmorris 2y ago
    > 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/fakeit.pdf https://users.ece.utexas.edu/~perry/education/SE-Intro/fakei...
    - iainmerrick 2y ago
      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.
Nexialist 2y ago
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 https://rfd.shared.oxide.computer/rfd/0177 Main index: https://rfd.shared.oxide.computer https://rfd.shared.oxide.computer
- esafak 2y ago
  This is an awesome format, esp. the diagrams. I am glad to see the tools are public: https://github.com/oxidecomputer/rfd-site https://github.com/oxidecomputer/rfd-site
swah 2y ago
I guess in the open source side we would talk about Github projects with the greatest READMEs...

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.

rullelito 2y ago

Companies keeping their IP a secret? Weird..

faizshah 2y ago

Chromium: https://www.chromium.org/developers/design-documents/ https://www.chromium.org/developers/design-documents/ Kubernetes: https://github.com/kubernetes/enhancements/tree/master/keps https://github.com/kubernetes/enhancements/tree/master/keps

iainmerrick 2y ago
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/sig-architecture/4402-go-workspaces 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/sig-architecture/4402-go-workspaces#implementation-history 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?"
- jppittma 2y ago
  Google is a huge company with ~180,000 employees. Sometimes people do sensible things.
  - iainmerrick 2y ago
    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?
- pjmorris 2y ago
  > 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/fakeit.pdf https://users.ece.utexas.edu/~perry/education/SE-Intro/fakei...
  - iainmerrick 2y ago
    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.

Nexialist 2y ago

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 https://rfd.shared.oxide.computer/rfd/0177 Main index: https://rfd.shared.oxide.computer https://rfd.shared.oxide.computer

esafak 2y ago
This is an awesome format, esp. the diagrams. I am glad to see the tools are public: https://github.com/oxidecomputer/rfd-site https://github.com/oxidecomputer/rfd-site

swah 2y ago

I guess in the open source side we would talk about Github projects with the greatest READMEs...