Hi all! After being a little unhappy with the way that docs are required for language features, especially with regards to the upcoming epoch. As such, I want to get some discussion going before I make a formal RFC. So here it is!
Replace most of RFC 1636 with a requirement of opening issues for documentation for language features, rather than requiring that documentation land prior to stabilization. This will significantly un-burden the process for stabilizing a feature, while still ensuring documentation is written. Library requirements remain the same.
RFC 1636 has a noble goal; to make sure that everything is properly documented. From its motivation section:
At present, new language features are often documented only in the RFCs which propose them and the associated announcement blog posts. Moreover, as features change, the existing official language documentation (the Rust Book, Rust by Example, and the language reference) can increasingly grow outdated.
However, due to a few factors, the way this has worked out in practice is suboptimal. Reading closely, it hasn’t even been implemented correctly. Quoting its text again:
Prior to stabilizing a feature, the features will now be documented as follows:
- Language features:
- must be documented in the Rust Reference.
- should be documented in The Rust Programming Language.
- may be documented in Rust by Example.
- Standard library additions must include documentation in std API docs.
- Both language features and standard library changes must include:
- a single line for the changelog
- a longer summary for the long-form release announcement.
Stabilization of a feature must not proceed until the requirements outlined in the How We Teach This section of the originating RFC have been fulfilled.
The changelog portion, for example, has not ever been done, to my knowledge.
Let’s talk about what happens today when a new language feature is proposed. A pull request is opened against the book, the reference, Rust by Example (RBE), and possibly the Nomicon. Because these resources describe stable Rust, and the feature is not yet stable, these PRs will always fail CI, making it hard to know if the PR even works. Then, they sit until the feature is stabilized. Sometimes, last-minute things pop up in the compiler, meaning that the PR can sit open for a month or more. In fact, if someone wanted to be proactive about docs, this hurts even more, as the docs PR will be open for even longer. So the incentive becomes to do the docs at the absolute last minute, and make them as small as possible. Then, once the feature becomes stable, we can re-run CI, see if it’s green, and merge the docs.
Furthermore, each resource has different requirements that makes this process akward:
The book has its own train schedule, separate from Rust releases. The current in-progress edition of the book is written for Rust 1.21. To help with this, an appendix is added, so that some text can be added here to satisfy the documentation requirement for stabilization. However, this means that at a later time, Carol and/or myself have to do work to integrate this into the main text itself. So, while it technically exists, and is a helpful start, readers of the book won’t even neccesarily see this feature as anything other than a blurb, and they won’t become aware of it unless the specifically seek this index out.
The book is also not exhastive; some features aren’t described, or are only partially described. This means that some stabilizations don’t even require updating the book as-is today.
The reference is not a spec, but we try to also keep it to a high degree of quality when possible. Since it’s not actually a spec, it’s unclear to what degree features need to be documented in the reference, and so the incentive is to make it small. Once the reference turns into a spec, more work will be need to done to spell out everything in exacting detail; similar to the book, the documentation requirement doesn’t ensure that the docs are good, just that they exist in some form.
Rust By Example and the nomicon
RBE and the nomicon are works that were adopted by the Rust docs team, and have little mini-teams forming around them to do work on them. However, they’ve always been a bit under-staffed, as it were. This can make getting timely reviews hard, and with the lack of high-level vision means it’s not always clear what to put and where.
The actual proposal
So, given these issues, I propose instead that an issue is opened on each repository, specially tagged so that the docs team can be aware of the outstanding list at any given time. The text of the issue would be the text that previously would have been sent in as a PR.
This ensures that the status of docs for each feature is known, but doesn’t lead to complex CI issues. It also means that it’s still discoverable by users, we still have the same text as we would have had before, and we don’t need to block things unneccesarily.