I’d be happy to take this opportunity to give credit where it’s due. Recently I’ve been working with @Alex_Martini, who’s done a lot of the writing for TSPL over the years and will, I hope, continue to have time for it going forward.
But Alex has a lot of other demands on his time; I cannot volunteer new work for him.
But, they should be at least responsible for writing a special section in the proposal, a section intended to serve as the repository of clear and coherent information and of examples to guide those writing the actual documentation itself.
Furthermore, that section also needs to be scrutinized during the proposal review.
Asking from a different direction, if one is interested in contributing to TSPL or other forms of documentation, what is the process for that? Is it as simple as opening a PR?
I believe the statement in the readme still applies: GitHub - swiftlang/swift-book: The Swift Programming Language book
If Swift is to be healthy, its users must be able to easily understand it, including any additions.
At the very least, the book ought to link to the adopted proposals. At best, each proposal ought to include a rough draft of the changes to the book. This inclusion would help the proposer to clarify the ideas, and would help the approvers to understand the proposal.
I am still very new to Swift, I just have the feeling Swift user experience is not about lack of features, but cleaning up the tech debt.
Swift means fast but it has to be steady if Apple wants Swift to be as good if not better than Java, maybe slow down a bit and fix the problems first
OK, I let this sit a week while I was out of town, but am ready to push it forward.
It looks like there is continued consensus that we need to add better defined documentation requirements to the process. I'll volunteer to make proposed changes to the template and link the branch here for feedback once I've finished. (unless someone else is already handling this)
Each steering group defines the Evolution process and template under its purview—you'll hear if the group has further thoughts to announce on any change related to documentation, but we're not soliciting PRs at this point.
OK, but I propose that we at least implement these two asap. That will really really help and are easy fixes.