Yes, it should be improved. It is hard to get started using existing documentation. You basically need to understand all of it (a lot) to get a good grasp of various patterns and practices. However, it is not that straightforward on how exactly to improve it. The current docs assumes you have have thread/async programming experience and builds upon that (for example,

GlobalScope.launch

is what you typically do nowadays), showing how to improve your code with structured concurrency a bit later. If we jump right away into the structured concurrency, as you suggest, then there is a risk it’ll look totally like magic for readers, so that people with a prior threads/async experience will have no way to bridge it to their existing knowledge.

In a recent paper of yours, you cited another paper: “Notes on structured concurrency, or: Go statement considered harmful.” which was excellent. I implore you to follow up on that paper showing how “Nurseries” compare to Kotlin and how to programmatically add a coroutine to a running nursery. This in your copious spare time of course. 🙂