Result builders are described in TSPL, in the “Advanced Operators” section for some reason.
1 Like
My bad, as they’re also mention in attributes. Search function didn’t get me that far heh
i personally think the way we talk about documentation in this community is not very productive. i share many of the sentiments in this thread (“how does one iterate a parameter pack?”) but introspection over time has made me realize we often think of documentation as something somebody else ought to write for us, and that when i complain about missing documentation what i am really saying is that somebody else (usually somebody at Apple) should write documentation about something i am using instead of doing whatever else they might be working on at the moment.
instead, i think documentation is something all of us generate passively through things like Forums threads, compiler engineers answering questions, Slack discussions, et cetera, et cetera. most of the information that people are looking for, i think, already exists somewhere in casual Q&A form, it is just not very discoverable, and it is not very discoverable because it is not very indexable.
the Swift Forums have never had a great search feature and i think this problem has gotten much worse in recent times for reasons such as Stack Overflow dying and a growing trend in this community of preferring the Swift Open Source Slack over the Swift Forums.
we should really start making a conscious effort to discourage people – especially experienced engineers – from asking questions on Slack and redirect them to Forums, which is more indexable and allows this community to retain control over its data instead of selling it (giving it away?) to Salesforce. and we should try to recruit an LLM and give it access to the discussions on these Forums, so that it can index them and so that we can ask the model questions and have it provide answers for topics that have already been discussed in the past.
Slack, i think, is one of the worst things that ever happened to this community from an educational perspective. we traded long-term indexing for short-term convenience, and it just ended up wasting more of everyone’s time answering the same few questions over and over again.
14 Likes
While I understand this viewpoint, those things aren't documentation, they're just information. Some of it may be correct, some of it may not be. Some of it may be out of date. Someone could probably read it all and distill it down to actual documentation, but that's probably more difficult than actual documentation writers sitting down with engineers to distill out the same information right from the source.
A major secondary issue is that, for the documentation we do have (the proposals), it may not line up with the actual implementation, and it's impossible for us to know whether the differences are intentional or bugs. We see this today with parameter packs, as @davedelong ran into, or as many people, myself included, ran into with concurrency when it first shipped. To some extent this is natural, as bugs occur in all software, but when it takes many months for fixes to ship (regardless of when the fix was actually made), such issues get encoded into the online discourse and people's understanding of features because they must work with the broken feature for so long. My own understanding of concurrency is deeply warped because I adopted it immediately but couldn't reconcile what I was seeing with what the proposals said.
Personally, while I think the community could help with this issue, and many have made heroic strides in that direction, I don't think it can really be solved without major investment from Apple. It employs virtually all of the subject matter experts, has the resources to hire whoever they need, and already employs some of the best doc writers around (though not nearly enough). I'm also not a huge fan people doing for free what a trillion dollar corporation could easily pay for.
11 Likes
I would love this... if this site actually allowed those questions.
Every time I talk to developers who are learning swift (including one just last night!), every single one mentions how they google to get help with their Swift app, find the Swift forums here, ask their question, and then get told to go elsewhere because they're really needing help with SwiftUI or some platform specific thing that is not precisely Swift-the-language. This website is absolutely not a welcoming place for questions.
10 Likes
Maybe one thing that could be added to the swift evolution process towards improving documentation without slowing down the process is a call to action in the proposal acceptance post to encourage anyone in the community to contribute in the TSPL.
Approved proposal would have a respective issue open in the swift book repository and the issue linked in the acceptance post.
7 Likes
Evolution proposals can serve as documentation for users, provided they have a special section which is written in a way that's easy to understand, and which provides examples that illustrate how the proposed feature would be used. However, doing this requires some discipline, which is currently missing.
I have stopped reading TSPL. I now read the evolution proposals, but sometimes I struggle to imagine how a feature would be used in real life, simply because a simple illustrative example is missing.
2 Likes
But implementation is an integral part of a Evolution proposal. It's required to start a review and it's part of the proprosal's final status (e.g. "Implemented (Swift 6.0)"). It's just that it's not reviwed as part of Evolution process. could documentation be given the same priority?
IIUC the fact that a propsal starts and typically ends with an implementation doesn't make the process more onerous. Is it possible to handle documentation same way? For example, adding a metadata for documentation status in a proposal. The metadata is only for information purpose (e.g. used by users and tools) and isn't required (e.g having "N/A" value) for proposal review. Ideally a technical writer should participate in the proposal review. But they could also choose to start working on documentation at later phase.
I think the concern of the community is that there isn't a mechanism to make sure this always works.
3 Likes
Exactly. I don’t need education. I just need documentation, as in the people designing the language writing down how the language is supposed to work in one place. If proposal authors cannot be expected to write updates to TSPL, perhaps there needs to be a spec of some kind that proposal authors can be expected to update. (Interestingly, the one part of the language that does have a formal spec, namely the grammar, seems to get updated more often.)
5 Likes
The quality of the documentation about a programming language is part of the user experience of the language as a whole.
I don't know if updating documentation should be part of the SE process.
But it should be part of the Swift release process. I.e. when a new version of Swift ships, it should ship with updated documentation. This means that when a proposal is accepted, it may find its way into a Swift version when it has a good enough quality implementation (because SE proposal does not require a final implementation) as well as an update to the relevant documentation. That latter part would be new.
Personally, I don't fear this will make less proposals go through. If a proposal is well enough that it passed review, it should be valuable enough to invest the time and effort to update the documentation. Especially as this will help the proposal get used in practice.
12 Likes
Because there is no formal language specification, I consider evolution proposals to be the source of truth. Therefore, I expect them to be the place where all the critical information which will be input to TSPL is kept and maintained meticulously.
If this is done with love and properly, the effort required to produce accurate and up-to-dateTSPL and release notes would be significantly reduced. The process can almost be entirely automated. 
Haven't seen anyone mention the fact that writing the documentation for a library or API quite often ends up triggering improvements to that design/API/etc.
Something about having to explain to someone else how to think about the library/API and how to use it reveals design warts that could be improved (API design and resulting usage patterns, naming, and so on).
This suggests there is potential benefit to the implementation by requiring at least a version of the documentation done earlier than after the implementation is merged.
14 Likes
I think this is something that is getting missed — SE has already become some sort of the documentation by itself, because there is no other way to find out about some of the features. It is just fragmented, so you also have to search for all relevant proposals to make sure you have up-to-date state of the language. From that perspective, I don’t see any harm of making proposal to create amendments to the language documentation, which can be just merged into the relative repository once the feature is released.
3 Likes
May be right approach is that proper documentation should be a requirement for a feature to reach "implemented" status instead of "accepted"?
First of all, some proposals while "accepted", aren't immediately implemented for a while. (SE 0283, 0246 for example). If the features is not implemented, it should not be documented as part of language reference, as it would be confusing.
On the other hand, proper documentation is a part of "implementation", since implemented features are barely usable unless documented, and 99% of users wouldn't even be aware they exist.
8 Likes
It seems that practically everyone is in agreement that we have a documentation issue. Consolidating all of the thoughts from the discussion so far, here are some proposals for discussion that I think don't overcomplicate the process and move us in the right direction:
-
The proposal is updated as the reviews and implementation further define it so that when the feature is merged, the proposal accurately describes the implemented feature. In the Review section, in addition to Pitch and Reviews, there will be 1st Proposal, 2nd Proposal, etc... that archive each version of the historical proposals. These would point to the commit (or tag) containing that version of the proposal. We could only tag these in git, but I think that having them in the proposal header is better for those who want to understand the evolution of the proposal.
-
We add a Documentation line to the proposal header that points to the documentation of the feature in the TSPL Guide and Reference sections. This is not expected to be filled in immediately and instead would contain status at first. But is expected to be complete when the feature is no longer behind an Upcoming Feature Flag. This allows brand new features to be present and usable in the released compiler versions while usage is still being worked out, but at the point that the feature is considered ready for general use and it is no longer behind a flag, it is documented.
-
The proposal authors are not required to write the documentation, but they are required to make sure that the documentation gets written. As mentioned a few times, writing good documentation is an art. Some proposal authors absolutely could do this, especially if it is a simple change to the documentation. Others would work with an author on the documentation team to get the information into the TSPL. (It may be that we always want to have the proposal authors work with an author on the documentation team.)
-
We add RFC style Obsoletes xxxx, Obsoleted-By xxxx, Updates xxxx, Updated-By xxxx headers. It is far too difficult to figure out how proposals are changed by future proposals. This is a solved problem with RFCs and it works quite well (as someone who has implemented many RFCs).
There is an open question of if/how we would apply these to past proposals. I'd suggest that the authors retroactively do it and if the author is unable to do so, some of us would handle those cases.
Thoughts on this?
21 Likes
Great idea.
To be honest, one can use LLMs to update documentation. It can write decent text, but will require someone who understands the subject to go over it and do some proofreading (it requires proofreading anyway, TSPL has some code that doesn't work or produces warnings at the moment of writing). May be it is not the ideal way to it, but it would be better than having no documentation at all. Also I assume it could be done relatively quickly.
1 Like
Or perhaps they're only responsible for starting a thread with the actual status, and the forum can have a go?
After the implementation is finalized for initial release, contributors start a forum thread for user-level documentation via forum. The thread would start with the final technical status (i.e., brief contributor-level understanding). The forum discussion would then evolve documentation, as a community reference and a starting-point for TSPL writers. That way, contributors can offload their knowledge quickly (but still monitor to detect flagrant mistakes), the community/forum gets some source of truth, and TSPL writers get someplace to start.
(TBH, I think the forum response should be accompanied by demonstration code that works in a git repo, so affording a repo with per-proposal code for collaboration would be great.)
It's possible this looser process doesn't bear fruit, but it seems worth trying. Indeed, proposal contributors can just opt in to this without any requirements or agreements from any Evolution powers-that-be, or it can be canonicalized as a practice that's recommended but not required.
1 Like
Definitely would require close proofreading. 
I think that this is a way that the documentation could move forward, but in my experience, if you don't have someone who at the end of the day is responsible for it, it very often doesn't get done. So starting the thread, but having ownership as part of the proposal implementation. (That may come naturally if the feature isn't allowed to come out from under a flag until the documentation is there.)
1 Like
Just as one data point from another community that runs a similar process, in Kubernetes KEPs, a feature is not allowed to get enabled in a release unless the documentation is also updated in the same release.
(R) Design details are appropriately documented
User-facing documentation has been created in kubernetes/website, for publication to kubernetes.io
So if a feature is implemented behind a feature flag and the author is too busy to ensure it's documented? That's okay, it'll stay disabled behind a feature flag till the next release, or whenever the docs are updated. But at least the documentation is considered an inseparable part of the feature delivery, rather than a nice-to-have, and the incentives are aligned properly between the proposal author and the users.
Not saying we need to copy the exact process, just that our community isn't the first one to encounter this, and other communities have solved this problem successfully.
26 Likes
@John_McCall are these technical writers available for further work on TSPL?