Why is Swift's Concurrency still lacking proper documentation?

After reading this post, I have felt compelled to say a few words.

I have learned quite a bit from the discussion preceding that post, but its aftermath has left me feeling a bit sad.

I am just wondering why the Swift Concurrency still lacks a unified, coherent, and properly written document. Why can't Apple take this problem seriously and do something about it?

I hope somebody from Apple with managerial responsibilities sees this post. :slight_smile:

7 Likes

In a prior conversation with @Joseph_Heck, I voiced similar concerns and also discussed possible improvements. However, as you have noted, the current easily accessible documentation severely lags behind the current state of the implementation. Overhauling it will require major time commitments and manpower, which we simply lack. At least this is my understanding of the current situation.

Personally, one possible way to improve the documentation, which I also mentioned in the conversation, would be to create a glossary with comprehensive documentations covering all of Swift’s keywords and attributes, starting with the concurrency relevant ones. So far, however, I haven’t found the time to actually work on it yet.

Other low(er)-hanging fruits I can think of include making the WWDC videos more accessible and writing additional in-depth articles that still target regular Swift users.

P.S. Check out the Swift Migration guide if you haven’t already, especially the “Data Race Safety” article.

P.P.S. A while back, I created a repository to make it easier to find official concurrency-related resources.

3 Likes

The referenced thread really highlights the nuances and, in some cases, surprising behaviors around function conversions. Does the current implementation work as intended? And, is that desirable? It would take me considerable time to even decide.

I still there are a lot of areas where the concurrency implementation and language design could use some attention. In an ideal world, I wouldn't have to make trade-offs. But if I had to allocate resources, I'd spend them elsewhere.

However, I also want to make sure this isn't just a blind-spot of mine. Do other feel like these are common and/or serious usability issues?

3 Likes