Hi all, there was a brief discussion in the Documentation category about this issue. The link is here, but the discussion really belongs here. I'll summarize my comments from the link.
The lack of complete, accurate documentation is probably the largest drawback to using swift at this point, especially for advanced usage. The docs used to be great, but they haven't kept up with the language and trying to weave your way through SE proposals that might also not be up to date is next to impossible unless you are following the language discussions daily. Note that this isn't a knock against the doc team at all. The problem, imo, is that swift evolution doesn't require document updates for proposal acceptance and inclusion into the language.
Most of the time, the user of a feature doesn't need to know all of the discussion and implementation details that go into a proposal. Instead they simply need to know when they would use a language feature, how they would use it, any edge cases, and have a couple examples to look at.
In addition, often times a given feature is split and/or refined over many proposals, so getting at the current usage can be very difficult.
There have been prior discussions on this point (for some reason, not coming up on search results), and while the problem is certainly correct and needs fixing, I don't think Evolution is the right place to fix it for a few reasons—some stated surely more eloquently elsewhere:
The Evolution process is already onerous: it has many steps, and the proposal text already incorporates many considerations. Participants have asked for ways to simplify these requirements so as to broaden how accessible the process is to the community; adding a documentation requirement would cut against that goal and we have thus far declined to do so on those grounds. "Complete, accurate documentation" is very hard to write and simply not a skill (to anywhere near that level, at least) that we can reasonably demand of authors.
To have a meaningful say in what is implemented and released, the Evolution process must necessarily precede release. Obviously, the intention (which we screen for) is that every feature is implementable in a shippable way, promptly and in its entirety—but that can't be guaranteed: the only guarantee of a releasable implementation is an implementation that is actually released. Accepted features may ultimately be only partially implemented or not at all, and documentation is not accurate if it speaks of features that don't (or even can't) exist.
When it comes to user-relevant documentation, "especially for advanced usage," the problem isn't simply that such documentation isn't written down at the time a feature is proposed: that information may not be known or even knowable at that time. Take, for instance, advanced concurrency: best practices for the advanced user, particularly distilled down to "a couple examples," alongside coverage of "any edge cases" requires extensive usage experience of a completed implementation. This in turn requires actually broadly shipping a completed implementation, which requires (several) approved proposals—which can't be held up for lack of this information.
The upshot of this: "complete, accurate documentation" of what's already in a release is hard enough—I can't see a practical way to demand it prospectively.
If there is no complete up-to-date documentation that describes how the language is supposed to work, how should someone know how the language is supposed to work?
Thanks for the reply. I also seemed to remember this being discussed in the past, but don't remember any resolution (and also couldn't find it when I searched).
I agree with you on keeping acceptance as simple as possible. Perhaps then the feature should not be considered a part of an official compiler release until documented (it could always be included behind an upcoming feature flag), i.e. all compiler releases have user documentation for all of their released features.
Complete accurate documentation is indeed very hard to write, but it is doable and was the norm until a decade or two ago (I'm dating myself :). And that documentation is part of the language contract. And that contract is incredibly important. Many wasted hours are spent on "am I doing this wrong or is it a bug in the program" when there isn't proper documentation. (Tech writers are unsung heroes imo.)
Also agree that the documentation (and examples) will evolve as the usability of the feature is discovered, but that shouldn't preclude documenting all of the features to start with to the best of our abilities.
I do understand that this isn't easy, but documentation of a language used to be the norm.
Right—as I said, this is certainly a problem and needs fixing; that does not mean that the Evolution process is suited to driving that fix.
I don't want to give an erroneous impression on this point: we do have drafting standards (or, if that is too strong a word, at least expectations) for language proposals, and chief among them is that the intended language contract is documented completely and to the best of our abilities.
That there are bugs and omissions in the compiler implementation is an unavoidable consequence of what I discussed above, but if you find specific instances where the intended design itself (yes, of all of the features proposed) is not understandable or is inaccurate from the proposal text, then that is a defect which we should (and will) correct.
What might be useful is keeping track of the documentation state of proposals that are accepted, ideally with links to that documentation. This could serve a dual purpose of providing a reference for people learning about a feature via the proposal, while also providing somewhere to point at when people want to advocate that it’s time to put that documentation together.
I don't want to give an erroneous impression on this point: we do have drafting standards (or, if that is too strong a word, at least expectations) for language proposals, and chief among them is that the intended language contract is documented completely and to the best of our abilities.
That's really good and the proposals should be required to do that. But the proposal serves a very different purpose than a language guide and reference. As a user of the language, I read the proposal, but there are 3 revisions. Now I have to read 3 revisions and figure out how they've changed the proposal. And sometimes, that isn't even enough and I have to go to the revision discussion to figure it out. And then I find out that this proposal has then been modified by a couple of other proposals (with their revisions and discussions) and the time consumption spirals just to learn how to use a language feature. All of that absolutely belongs in the proposal chain, but not in the documentation.
This affects me personally, but this is also not an easy entry into the language at all for new users. And it is especially true for those who need the advanced features as soon as possible. A few months ago, I handed a project off to another veteran developer who was new to swift but had a tremendous amount of obj-c, c, and c++ experience. Telling him to read the language guide let him understand 75% of the code. But trying to get him the correct documentation to understand something like isolation was incredibly hard and he was completely overwhelmed. "You have to read this proposal, but it's not quite like that anymore, so read this other proposal afterwards, but that particular feature has had its name changed (check the revisions) and this other feature is now completely different because of this other proposal..." and on and on...
What might be useful is keeping track of the documentation state of proposals that are accepted, ideally with links to that documentation.
I think that's a great start. But there also needs to be some form of accountability for documentation of the feature before it is considered released imo.
The Evolution process is the process that is making changes to the language without updating the documentation. It is the very source of the problem. What better place is there to fix the problem?
The problem is that the intended language contract isn’t described by any one proposal, since they supersede one another. To get a complete understanding of the language in some area you may have to read 5-10 proposals sometimes stretching back several years.
Evolution implies change, proposed and actual. Without changing the process of proposal through release, a minimal statement of actual would avoid taxing consumers with an archaeological dig for the truth.
What's the minimum change that would make a difference?
Assuming:
Proposals are accepted during or before implementation.
The release process cannot be gated extrinsically
The work of writing good documentation for the language is not managed through Evolution
We still need some BOM, a statement of what was actually delivered - after the release. Some combination of
Revision of proposal text, if it was mostly accurate, or just a fresh statement of actual functionality in light of new understandings
List of known bugs and limitations
These descriptions are expressly not documentation for users, but technical accounts between contributors, that can make assumptions about related contributor knowledge. They're only intended as a snapshot of functionality at the time of release. (Tracking status and bug fixes is a separate matter.)
Some single source of truth would help tremendously with all the downstream needs - insider learning, updating TSPL, and just using the language.
Swift Evolution is not "the process that is making changes to the language"—it is one piece of it. Crucially, implementations and releases are outside of its purview: Evolution decisions are not self-executing, and there is at least one example of a proposal where the proposing team disagreed with the ultimate decision and simply declined to implement.
The practical effect of imposing any incremental requirement on the Evolution process is that fewer proposals will go through the process. Requiring user-facing documentation to be generated for a feature that may not have a shippable implementation will slow time to review. Yet for all that extra work, it can't guarantee that "complete, accurate documentation" gets shipped; in fact, I'd worry it could perversely increase the probability that documentation gets shipped which has fallen out of sync with the actual implementation.
I agree with the problem articulated: the information is there to be found, but it hasn't been reworked into a format that effectively serves end user needs. Again, I think you've all identified a real and important problem that's in need of a solution.
As you say, the proposal text must serve various audiences and purposes, and end user didactics is one of these but not primary. I don't think that requiring proposal authors additionally to write and re-write mock documentation which (in the scenario above) becomes inaccurate by the next proposal achieves the desired end result. Nor is it workable to require whichever author comes last to write documentation for a half-dozen proposals in order to make a small but crucial amendment, say, to the concurrency model.
Yes, again, this is a real and important problem: it's clear that there is an appetite for guidance on new language features, including (and perhaps especially) advanced concurrency.
(It bears saying, however, that as with all advanced features requiring widespread user experience to accumulate best practices—including, mind you, pedagogical best practices—being an early adopter who jumps in "as soon as possible" or waiting until there's "easy entry" with succinct tutorials and guides are necessarily two poles of a continuum that isn't straightforwardly collapsible.)
The requirement as it now stands is that the proposal author must (with guidance if needed) do well enough explaining the proposed change for the purposes of review. As has been well said above by @jasonbobier, that is not the same as writing to educate end users. (Nor does it mean that the author necessarily grasps all the implications of the proposed change: that is why we run a review.)
Doing and teaching are distinct, and we all know people who excel at the former but are hopeless at the latter. In another setting, you might want to hire only developers who have both skillsets, but we don't—and I wouldn't—gatekeep the Evolution process in that way.
There is a phrase in game design: ”designing for the teach”. Meaning if you can’t explain a rule to new players, you change the rule until you can, because it leads to better designs.
I really can’t see how it would be ”gatekeeping” to require authors to suggest updates to TSPL along with their proposals. Surely Swift is made for its users, not for proposal authors? If we’re putting the needs of proposal authors over the needs of users, what are we even doing here?
Just recently I was deeply confused about the latest iteration on concurrency and said to myself “ok, let us re-read everything from the spec so I know exactly what is being discussed”, and I faced the harsh reality that the language spec is not remotely suitable.
Because I follow a bunch of interesting people on social media in despair I googled “massicotte glossary swift” as he has been heroically keeping up with things. Then I read his blogs back to front, then I read his recipes.
The glossary is fabulous, but it still links to documents that later get revised, so it is not as straightforward as just reading all the above.
But newcomers and returning users shouldn’t have to spend a few weeks soaking in the community to know that “massicotte” is the google term they need to get cooking.
I am spiritually aligned with the “evolution proposals should include a diff to the language spec”. Tactically, the issue is that right now the language spec has a debt large enough that it is probably a task that requires paid developer relations people that have a solid grasp on the subject matter to make a dent.
We have actually been working with some technical writers to revise TSPL for the recent concurrency changes. Again, though, writing book-quality documentation is not something we can reasonably expect every proposal author to do in advance of the review.
These feels like part of the issue though. "Book-quality" feels like far too high of a bar when things are so lacking. ANY documentation would be welcome. Even poorly-written documentation is, IMO, better than the status quo of "no documentation".
I've hit this frustration when trying to figure out what's going on with Parameter Packs. I google and google and keep getting dumped back in to proposal documents and have no idea if they've been superseded or not, or if I'm hitting stuff because I'm wrong or if it's because the feature just doesn't exist.
Result builders are a golden example of a language feature used everyday now (via SwiftUI), has been in the language for a few years now (not new), and has absolutely no confusing mention in TSPL.
It’s been annoying talking about them with peers and can only describe them as “compiler magic” or “just read the SE”.