Are SE proposals supposed to be used as 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