Are SE proposals supposed to be used as documentation?

I am sorry if it sounds as a complaint (because it is not), but what is the place for Swift parts that are missing, or very scarcely documented in TSPL? Take ~Copyable or macros for example. ~Copyable didn't appear in 6.0 version of the book (I don't know about 6.1, as it is not searchable and there is no official pdf version yet, and I didn't try to generate the pdf myself yet), and I am sure that most of the readers have very vague idea how to implement macros after reading the corresponding chapter in the book.
Same goes to the concurrency chapter - most of the code doesn't work and the descriptions are very superficial. So, where is proper place to look for these? Are we supposed to read through SE proposals? If this is the case - are they guaranteed to be correct and updated when the language changes?

13 Likes

It's really tough. The lack of complete, accurate documentation is probably the largest drawback to using swift atm. It used to be great, but the docs 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. It's a knock against the language evolution and its lack of documentation requirements.

5 Likes

@theundergroundsorcerer is it possible for you to add Using Swift and Evolution to this post? Because this really needs a serious discussion in more than just Swift Documentation.

I think to some extent, they are documentation.

Apart from end user-oriented text, the proposals usually contain valuable motivations, examples and rationale. Among all "official" text talking about Swift in the community, I often found certain pieces of information only exist in some proposals.

That being said, when newcomers come to read the proposals, they might be frustrated for some reasons:

  • The proposals sometimes contain information not reflecting the current state, especially for proposals of ages.
  • Some proposals are not self-contained and they must be read alongside other ones.
  • Not all information are directly relevant and may distract learners.

I guess there can be some improvements in this area, possibly they go align with Announcing The Swift Information Architecture Project.

1 Like

I agree on this, this post can be moved into other categories to gain more attraction, for example, into "Using Swift", or "Evolution/Discussion".

1 Like

This is the problem imo. End users of the compiler shouldn't need to read the proposals to get information about how to use a feature because most of the time they don't need all of the information that goes along with making a proposal (rational, motivations, revisions, etc...). And newcomers absolutely shouldn't need to read them. That information along with any changes and examples should be in the documentation once the proposal is accepted. And should they be interested in those things, they can always go to the proposal afterwards.

3 Likes

Another issue is that many times a given feature of the language is split and/or refined over many proposals, so getting at the current usage can be difficult.

3 Likes

FYI, discussion of this issue taking place here: Swift Evolution proposal acceptance should require that the The Swift Language Book be updated

1 Like