The state of Swift documentation

[wowbagger (冀卓疌)]

In addition to what others have posted, here is something from my observation, along with a suggestion for improvements:

1. Documentation of Swift Package Manager is scattered in 2 parts on swift.org: its API documentation is grouped in and accessible through the "Documentation" page, and the more tutorial-like part is grouped in the "Projects" section. Neither one provides links or references to the other.

2. I think the Language Guide part of The Swift Programming Language is a fantastic resource for first-time learners. My only problem with it is that it omits some important information. For example:

   • I had been confused by extra parameters in string interpolation in some APIs (appendInterpolation(_:align:privacy:) from Logger, appendInterpolation(_:style:) from SwiftUI, etc...), and it was very hard to track down how they worked, because the Language Guide's String Interpolation section never mentioned anything introduced by SE-0228.

   • The book failed to mentioned if/guard case let/var for optional binding, which, although aren't as widely used as if/guard let/var, have distinct behaviour and use case worth documenting.

---

I suggest that going forward, we should start requiring all new evolution proposals to include an evaluation on how documentation should be updated (when the documentation is closed-source like The Swift Programming Language book), and/or actually updating the documentation (when the documentation is open-source like the "docs" directory in Swift's repository)