A co-worker recently linked me to https://www.whatsnewinswift.com/. That's great, but it would be even better if SEs themselves took steps to make the changes their adoption leads to directly learnable.
This is an idea that's been taken up in a few communities already:
Ember's has a remarkable concern for the impact on the "notional machine" that its users have.
Rust has gone a step further to require documentation land along with stabilization, in the form of guide, reference, and examples.
Is this something you see as lacking in Swift? Would introducing a "How do we teach this?" to the SE proposal template be a useful step to improve things?
This would require an amendment to the proposal template. What does the Core Team think? Would it be a good idea to enhance proposals with more pedagogy and documentation?
We'll soon be reading very very tough proposals, as the work on ABI reaches its final stages. We already read delicate pitches here and there. The core team may miss the opinion of the "masses" if the subtle proposals to come are only written with implementation details in mind, and no meat for users.
I’ve found the “does this fit and feel” question in the review template does not itself answer what the path to learning a change looks like. It’s too easy to only analyze the spelling and names of a proposal instead of considering it as a holistic part of Swift. If learnability is discussed at all, it’s buried too deep in the pitch or review threads to have an impact.
Requiring this in the proposal would act as a proxy for the person consuming the change when it ships in a version of Swift. That’s ultimately a very important audience for a proposal, above the mercurial forums and sometimes even the Core Team. It would also help proposals live beyond the Swift Evolution process as a destination for when someone asks why something changed, something I greatly admire about the Rust RFC community.
I'm lightly in favor of adding a requirement like what you're suggesting. I'd prefer coming up with a carrot-based approach to this rather than a stick-based one, if that makes sense.
The Swift community is pretty great about writing about new SE proposals. I've seen a ton of variety in how people write, talk, and code about language changes.
I don't think Swift is much different than Rust in the sense that we update the language guide, language reference, standard library reference, and the associated examples as features are implemented and stabilized.
I like the general idea, but as I think through some of the specifics of how it would work, I'm not sure what we would actually write for many proposals. For example, consider the \.self proposal—does it just say "We will add a line to the documentation of each KeyPath class"? How much is that really adding to the proposal?
Similarly, most proposals which modify standard library APIs include doc comments in the code listings of their "Detailed design" section. Doesn't that suffice? Do we need to call it out in a separate section?
I feel like this is appropriate mainly for proposals which introduce new syntax (e.g. some of the string literal stuff I've had a hand in recently) or new subsytems with complicated semantics (e.g. UnsafeRawPointer and the concept of "binding" memory to a type). But I think there are a lot of proposals where the content would be very trivial.
(Then again, some of our existing sections often have one-sentence or even one-word answers, so maybe I'm overthinking this.)
As is the tradition of our tribe, I also object to the proposed name. SE proposals don't really have sections whose names are questions; even ones which really are prompting you to answer a question, like the "Effect on ABI stability" section, aren't phrased as questions. To fit the pattern of our other section headings, I'd suggest something more like "Teaching strategy".
Building on your ideas here, perhaps the carrot-based approach to prototyping this would be to take a look at some upcoming proposals, find a few that look trickier to teach, then contact the author and suggest adding a section about how the proposal is amenable to being taught. If they aren't comfortable doing it themselves, someone could volunteer to help write that part.
I initially thought this might be a good idea, but when I looked at a random set of EmberJS RFCs it didn't seem to be that useful in practice for most of them. Some proposals would benefit from it, but I'm not convinced it should be a required part of the template.
I appreciate your focus on a concrete example. I’d like to examine your example as well, so I can answer your question. Could you please link to the proposal you had in mind? A search for .self turned up two different proposals, so I’m not sure which you particularly want to discuss.
Re: Doc comments: Those are a particular form of reference documentation. They are quite far from a consideration of learning impact. Their focus is too narrow, and their purpose is different.
Re: Appropriateness: Perhaps the answer in some cases would indeed be something like “this doesn’t need teaching to people, and it won’t leak to error messages and confuse them, either”. That would be good to hear directly from the proposal!
Re: Section Naming: I’m not wedded to any particular name.
Instead of adding this to the proposal template, it could be one of the questions in the review template. There are users of the Swift Forums who teach professionally, and would be able to answer "How do we teach this?" during their review.
Oh, is it? I didn't know that, and couldn't find it in the template or the process description. Given that, it seems fine as an optional section, and perhaps the other sections could be reviewed for optionality at the same time. In particular, the “Source compatibility”, “Effect on ABI stability” and “Effect on API resilience” sections are often only filled out in a cursory fashion or explicitly marked N/A, particularly for additions to the standard library. The other sections seem fairly mandatory, though.
I think that documentation is actually the right focus for proposal authors. I don't think "How do we teach this" is something that can be answered in the evolution process. Answering that requires you do define the audience, and desired goal. I can imagine teaching (for example) KeyPaths very differently to someone who is a Java developer wanting to learn Swift to use SwiftNIO than I would an Objective-C developer wanting to modernize her iOS app. Vague answers to these questions (e.g., teach people learning swift to use feature Y) leads to vague and ineffective teaching. The evolution process is the wrong place to answer that question, and risks putting a burden on proposal authors that will not actually be useful to teachers and course developers.
Here is how Rust describes their section:
The section should explain what changes need to be made to documentation, and if the feature substantially changes what would be considered the "best" way to solve a problem or is a fairly mainstream issue, discuss how it might be incorporated into The Rust Programming Language and/or Rust by Example.
They restrict their discussion to specific documents. If we want to make this section about Language Guide and Language Reference updates, that would make it manageable, since the scope of these documents is defined, at least implicitly.
It can't be given a closed-form answer, but an answer can be attempted. Perhaps a better name in the context of the existing Swift proposal sections would be "High-Level Design", with questions like:
What named concepts are introduced or altered?
How does this fit in alongside existing Swift features? How is it intended to change existing practice?
Will even newcomers meet with its changes, or is this aiming at a more subtle or more expert problem?
For I note that Rust's focus is not so narrow as "what docs do we touch". The specific Rust section language is:
What names and terminology work best for these concepts and why? How is this idea best presented? As a continuation of existing Rust patterns, or as a wholly new one?
Would the acceptance of this proposal change how Rust is taught to new users at any level? What additions or changes to the Rust Reference, The Rust Programing Language, and/or Rust by Example does it entail?
How should this feature be introduced and taught to existing Rust users?
This directs the author's focus to:
Choice of terminology
Impact on Rust usage by existing users (by changing patterns and conventions or by needing to teach them something wholly new)
Impact on new users, if any (this is where most documentation updates appear to come in)
New users seem well-served by the existing documentation update process. It's the first two focuses that seem less considered by the current process. As it stands, the proposal structure seems to leap from motivation into the solution and its detailed, low-level impacts, without situating that solution in context. Sometimes the "Motivation" section may address some of this, but its focus is different enough that it mostly won't.
It seems to me that there are three rather different possibilities for what this section means:
How does the documentation need to be changed?
How does this change what we teach to new Swift programmers?
How do we explain this change to existing Swift programmers?
The first doesn't seem appropriate unless we're going to require proposals to include a documentation change the same way that they now have to include a prototype implementation, which I'm not sure is reasonable. Also, that would be difficult for language changes, since the main language documentation is The Swift Programming Language, which is not open-source.
The second and third are interesting to ask people to consider, but they are fairly different from each other.