The "Data Race Safety" chapter is challenging to read

[kkostov]

Hi everyone, I greatly appreciate the efforts to make Swift a safer language.

I'm opening this issue in response to a toot from @mattmassicotte in a discussion regarding the Data Race Safety guide, which is the first chapter of the Swift 6 migration.

My original (shortened to fit in a post) comment can be found here.

I find the current documentation challenging to navigate, particularly in understanding concurrency concepts, without expending a significant amount of time and focus pouring through docs and examples to understand how something works. I find myself asking "how to do X" or "what happens here" (example) but it's hard to find out if and where this can be documented.

Complexity: The documentation introduces many concepts (static/dynamic checks, actors, etc.) simultaneously, which can be overwhelming. For example, the initial sections assume familiarity with these concepts without explaining them in detail. There is a lot to ingest all at once - static and/or dynamic safety, actors, domains, regions, units, Objc makes an appearance, Swift language modes .etc. I can't imagine folks keeping all that in mind while say trying to execute a heavy workload without blocking the UI.

Practicality: It would help if the guides are to become a bit less "academically correct" and more practical and accessible, even visual (illustrations!!). More practical examples to begin with before going into advanced use cases, would help make it more relatable and approachable.

More neutral tone: Concurrency docs often use vocabulary like "Traditionally", "doing things correctly", "it is often useful to talk about" etc. which somewhat implies a judgment on the current state of understanding or practice. I think it will be better to focus on the evolution of the language and how to operationalise it, rather than implying outdated practices (feel free to do so in other articles, of course). e.g. Traditionally, mutable state had to be manually protected via careful runtime synchronisation. > In earlier approaches, developers were responsible for manually protecting mutable state to avoid issues like data races and ensure thread safety..