Consider publishing archived design docs.

[modulovalue]

It looks like there are Dart design docs that are not publicly available. One example of that appears to be go/dart-vm-const-maps https://github.com/dart-lang/sdk/commit/6c4f9f0045ad7e00e364a91ee51989e29e928247.

Consider, for example, Flutter, which has a straightforward process for writing and publishing design docs in a way that makes them available to people outside of Google: https://docs.google.com/document/d/1SFRO8U2toOlAaZ38dsuEU7Wm5fn41wvBCWKiwADqfmw/edit.

I believe that the wider Dart community would also greatly benefit from having access to Dart-related design docs.

I'm assuming that there are many more design docs and so I wanted to ask if a process could be established for archiving design docs in a way that makes them available to the public.

[mraleph]

I believe that the wider Dart community would also greatly benefit from having access to Dart-related design docs.

Could you list some example of how do you think the Dart community could benefit? What would you do if you had an access e.g. to go/dart-vm-const-maps? What do you think is there that could help you?

Design docs despite their name are not all that helpful for describing design once the implementation has actually happened. They are not documentation - they are alignment medium. They exist to drive consensus between developers involved in the design and implementation of a particular feature. More often than not they become outdated and useless rather quickly after implementation actually completes.

I am not against the idea of capturing design decisions as more detailed comments / docs (e.g. we have runtime/docs precisely for that purpose), but I don't think anybody would actually benefit from reading the raw design docs.

[modulovalue]

What do you think is there that could help you?

It's difficult for me to say, since I don't know how they are structured, but I'm going to assume that they roughly mirror the Flutter design doc template.

In my opinion, Flutter design docs are useful in the following ways:

• They contain a background section that provides a helpful summary of the problem domain.
• They point out suboptimal decisions that have been made before, which helps with not making them again.
• They are successful examples of how the Flutter team expects others to communicate with other Flutter team members about complex topics in a productive way.

Also, it is very helpful to immerse oneself into a topic as much as possible to become good at it. Outside of GitHub issues, and code, there's not much in-depth material to immerse oneself into when it comes to the SDK-parts of Dart. Of course, documentation is useful, but it focuses on the what and how, and not on the why, which I hope to learn more about from design docs.

What would you do if you had an access e.g. to go/dart-vm-const-maps

I would read it hoping to learn something new.

[modulovalue]

@mraleph recently, you've asked on social media about what could be done to encourage more contributions. I think that publishing design docs would be helpful in that regard.

---

Quote from Chesterton’s Fence:

A core component of making great decisions is understanding the rationale behind previous decisions. If we don’t understand how we got “here,” we run the risk of making things much worse.

There exists in such a case a certain institution or law; let us say, for the sake of simplicity, a fence or gate erected across a road. The more modern type of reformer goes gaily up to it and says, “I don’t see the use of this; let us clear it away.” To which the more intelligent type of reformer will do well to answer: “If you don’t see the use of it, I certainly won’t let you clear it away. Go away and think. Then, when you can come back and tell me that you do see the use of it, I may allow you to destroy it.”