From cf44e64ea33a22489ab83b9767634d7f2ae59c45 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Fri, 3 Jun 2016 22:34:27 -0400 Subject: [PATCH 01/23] Document all features. --- text/0000-document_all_features.md | 145 +++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 text/0000-document_all_features.md diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md new file mode 100644 index 00000000000..05a243c516b --- /dev/null +++ b/text/0000-document_all_features.md @@ -0,0 +1,145 @@ +- Feature Name: document_all_features +- Start Date: 2016-06-03 +- RFC PR: (leave this empty) +- Rust Issue: (leave this empty) + +# Summary +[summary]: #summary + +One of the major goals of Rust's development process is *stability without stagnation*. That means we add features regularly. However, it can be difficult to *use* those features if they are not publicly documented anywhere. Therefore, this RFC proposes requiring that all new language features and public standard library items must be documented before landing on the stable release branch (item documentation for the standard library; in the language reference for language features). + +# Motivation +[motivation]: #motivation + +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. + +Although the Rust Book and Rust by Example are kept relatively up to date, [the reference is not][home-to-reference]: + +> While Rust does not have a specification, the reference tries to describe its working in detail. *It tends to be out of date.* (emphasis mine) + +Importantly, though, this warning only appears on the [main site][home-to-reference], not in the reference itself. If someone searches for e.g. that `deprecated` attribute and *does* find the discussion of the deprecated attribute, they will have no reason to believe that the reference is wrong. + +[home-to-reference]: https://www.rust-lang.org/documentation.html + +For example, the change in Rust 1.9 to allow users to use the `#[deprecated]` attribute for their own libraries is, at the time of writing this RFC, *nowhere* reflected in official documentation. (Many other examples could be supplied; this one is chosen for its relative simplicity and recency.) The Book's [discussion of attributes][book-attributes] links to the [reference list of attributes][ref-attributes], but as of the time of writing the reference [still specifies][ref-compiler-attributes] that `deprecated` is a compiler-only feature. The two places where users might become aware of the change are [the Rust 1.9 release blog post][1.9-blog] and the [RFC itself][RFC-1270]. Neither (yet) ranks highly in search; users are likely to be misled. + +[book-attributes]: https://doc.rust-lang.org/book/attributes.html +[ref-attributes]: https://doc.rust-lang.org/reference.html#attributes +[ref-compiler-attributes]: https://doc.rust-lang.org/reference.html#compiler-features +[1.9-blog]: http://blog.rust-lang.org/2016/05/26/Rust-1.9.html#deprecation-warnings +[RFC-1270]: https://github.com/rust-lang/rfcs/blob/master/text/1270-deprecation.md + +Changing this to require all language features to be documented before stabilization would mean Rust users can use the language documentation with high confidence that it will provide exhaustive coverage of all stable Rust features. + +Although the standard library is in excellent shape regarding documentation, including it in this policy will help guarantee that it remains so going forward. + +## The Current Situation +[current-situation]: #the-current-situation + +Today, the canonical source of information about new language features is the RFCs which define them. + +There are several serious problems with the _status quo_: + +1. Many users of Rust may simply not know that these RFCs exist. The number of users who do not know (or especially care) about the RFC process or its history will only increase as Rust becomes more popular. + +2. In many cases, especially in more complicated language features, some important elements of the decision, details of implementation, and expected behavior are fleshed out either in the associated RFC (pull-request) discussion or in the implementation issues which follow them. + +3. The RFCs themselves, and even more so the associated pull request discussions, are often dense with programming langauge theory. This is as it should be in context, but it means that the relevant information may be inaccessible to Rust users without prior PLT background, or without the patience to wade through it. + +4. Similarly, information about the final decisions on language features is often buried deep at the end of long and winding threads (especially for a complicated feature like `impl` specialization). + +5. Information on how the features will be used is often closely coupled to information on how the features will be implemented, both in the RFCs and in the discussion threads. Again, this is as it should be, but it makes it difficult (at best!) for ordinary Rust users to read. + +In short, RFCs are a poor source of information about language features for the ordinary Rust user. Rust users should not need to be troubled with details of how the language is implemented works simply to learn how pieces of it work. Nor should they need to dig through tens (much less hundreds) of comments to determine what the final form of the feature is. + +## Precedent +[precedent]: #precedent + +This exact idea has been adopted by the Ember community after their somewhat bumpy transitions at the end of their 1.x cycle and leading into their 2.x transition. As one commenter there [put it][@davidgoli]: + +> The fact that 1.13 was released without updated guides is really discouraging to me as an Ember adopter. It may be much faster, the features may be much cooler, but to me, they don't exist unless I can learn how to use them from documentation. Documentation IS feature work. ([@davidgoli]) + +[@davidgoli]: https://github.com/emberjs/rfcs/pull/56#issuecomment-114635962 + +The Ember core team agreed, and embraced the principle outlined in [this comment][guarav0]: + +> No version shall be released until guides and versioned API documentation is ready. This will allow newcomers the ability to understand the latest release. ([@guarav0]) + +[guarav0]: https://github.com/emberjs/rfcs/pull/56#issuecomment-114339423 + +One of the main reasons not to adopt this approach, that it might block features from landing as soon as they otherwise might, was [addressed][@eccegordo] in that discussion as well: + +> Now if this documentation effort holds up the releases people are going to grumble. But so be it. The challenge will be to effectively parcel out the effort and relieve the core team to do what they do best. No single person should be a gate. But lack of good documentation should gate releases. That way a lot of eyes are forced to focus on the problem. We can't get the great new toys unless everybody can enjoy the toys. ([@eccegordo]) + +[@eccegordo]: https://github.com/emberjs/rfcs/pull/56#issuecomment-114389963 + +The basic decision has led to a substantial improvement in the currency of the documentation (which is now updated the same day as a new version is released). Moreover, it has spurred ongoing development of better tooling around documentation to manage these releases. Finally, at least in the RFC author's estimation, it has also led to a substantial increase in the overall quality of that documentation, possibly as a consequence of increasing the community involvement in the documentation process (including the formation of a documentation subteam). + +# Detailed design +[design]: #detailed-design + +The basic process of developing new language features will remain unchanged from today, with the addition of a straightforward requirement that they be properly documented before being merged to stable. + +## Language features +[language-features]: #language-features + +In the case of language features, this will be a manual process, involving updates to the `reference.md` file. (It may at some point be sensible to break up the Reference file for easier maintenance; that is left aside as orthogonal to this discussion.) + +Note that the feature documentation does not need to be written by the feature author. In fact, this is one of the areas where the community may be most able to support core developers even if not themselves programming language theorists or compiler hackers. This may free up the compiler developers' time. It will also help communicate the features in a way that is accessible to ordinary Rust users. + +New features do not need to be documented to be merged into `master`/nightly, and in many cases *should* not, since the features may change substantially before landing on stable, at which point the reference material would need to be rewritten. + +Instead, the documentation process should immediately precede the move to stabilize. Once the *feature* has been deemed ready for stabilization, either the author or a community volunteer should write the *reference material* for the feature. + +This need not be especially long, but it should be long enough for ordinary users to learn how to use the language feature *without reading the RFCs*. + +When the core team discusses whether to stabilize a feature in a given release, the reference material will now be a part of that decision. Once the feature *and* reference material are complete, it will be merged normally, and the pull request will simply include the reference material as well as the new feature. + +## Standard library +[std]: #standard-library + +In the case of the standard library, this could conceivably be managed by setting the `#[forbid(missing_docs)]` attribute on the library roots. In lieu of that, manual code review and general discipline should continue to serve. However, if automated tools *can* be employed here, they should. + +# Drawbacks +[drawbacks]: #drawbacks + +The largest drawback at present is that the language reference is *already* quite out of date. It may take substantial work to get it up to date so that new changes can be landed appropriately. (Arguably, however, this should be done regardless, since the language reference is an important part of the language ecosystem.) + +Another potential issue is that some sections of the reference are particularly thorny and must be handled with considerable care (e.g. lifetimes). Although in general it would not be necessary for the author of the new language feature to write all the documentation, considerable extra care and oversight would need to be in place for these sections. + +Finally, this may delay landing features on stable. However, all the points raised in [**Precedent**][precedent] on this apply, especially: + +> We can't get the great new toys unless everybody can enjoy the toys. ([@eccegordo]) + +For Rust to attain its goal of *stability without stagnation*, its documentation must also be stable and not stagnant. + +# Alternatives +[alternatives]: #alternatives + +- **No change; leave RFCs as canonical documentation.** + + This approach can take (at least) two forms: + + 1. We can leave things as they are, where the RFC and surrounding discussion form the primary point of documentation for newer-than-1.0 language features. As part of that, we could just link more prominently to the RFC repository and describe the process from the documentation pages. + 2. We could automatically render the text of the RFCs into part of the documentation used on the site (via submodules and the existing tooling around Markdown documents used for Rust documentation). + + However, for all the reasons highlighted above in [**Motivation: The Current Situation**][current-situation], RFCs and their associated threads are *not* a good canonical source of information on language features. + +- **Add a rule for the standard library but not for language features.** + + This would basically just turn the _status quo_ into an official policy. It has all the same drawbacks as no change at all, but with the possible benefit of enabling automated checks on standard library documentation. + +- **Add a rule for language features but not for the standard library.** + + The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. + + On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). + + +# Unresolved questions +[unresolved]: #unresolved-questions + +- How will the requirement for documentation in the reference be enforced? +- Given that the reference is out of date, does it need to be brought up to date before beginning enforcement of this policy? +- For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? +- Is a documentation subteam, _a la_ the one used by Ember, worth creating? \ No newline at end of file From 1ad0a00ce80039072de936b3331384bd21cc2cc6 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Fri, 3 Jun 2016 23:06:39 -0400 Subject: [PATCH 02/23] Add another alternative. --- text/0000-document_all_features.md | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 05a243c516b..e9c939d317b 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -118,22 +118,30 @@ For Rust to attain its goal of *stability without stagnation*, its documentation - **No change; leave RFCs as canonical documentation.** - This approach can take (at least) two forms: + This approach can take (at least) two forms: - 1. We can leave things as they are, where the RFC and surrounding discussion form the primary point of documentation for newer-than-1.0 language features. As part of that, we could just link more prominently to the RFC repository and describe the process from the documentation pages. - 2. We could automatically render the text of the RFCs into part of the documentation used on the site (via submodules and the existing tooling around Markdown documents used for Rust documentation). + 1. We can leave things as they are, where the RFC and surrounding discussion form the primary point of documentation for newer-than-1.0 language features. As part of that, we could just link more prominently to the RFC repository and describe the process from the documentation pages. + 2. We could automatically render the text of the RFCs into part of the documentation used on the site (via submodules and the existing tooling around Markdown documents used for Rust documentation). - However, for all the reasons highlighted above in [**Motivation: The Current Situation**][current-situation], RFCs and their associated threads are *not* a good canonical source of information on language features. + However, for all the reasons highlighted above in [**Motivation: The Current Situation**][current-situation], RFCs and their associated threads are *not* a good canonical source of information on language features. - **Add a rule for the standard library but not for language features.** - - This would basically just turn the _status quo_ into an official policy. It has all the same drawbacks as no change at all, but with the possible benefit of enabling automated checks on standard library documentation. + + This would basically just turn the _status quo_ into an official policy. It has all the same drawbacks as no change at all, but with the possible benefit of enabling automated checks on standard library documentation. - **Add a rule for language features but not for the standard library.** - - The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. - On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). + The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. + + On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). + +- **Eliminate the reference entirely.** + + Since the reference is already substantially out of date, it might make sense to stop presenting it publicly at all, at least until such a time as it has been completely reworked and updated. + + The main upside to this is the reality that an outdated and inaccurate reference may be worse than no reference at all, as it may substantially mislead Rust users. + + The main downside, of course, is that this would leave very large swaths of the language basically without *any* documentation, and even more of it only documented in RFCs than is the case today. # Unresolved questions @@ -142,4 +150,4 @@ For Rust to attain its goal of *stability without stagnation*, its documentation - How will the requirement for documentation in the reference be enforced? - Given that the reference is out of date, does it need to be brought up to date before beginning enforcement of this policy? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? -- Is a documentation subteam, _a la_ the one used by Ember, worth creating? \ No newline at end of file +- Is a documentation subteam, _a la_ the one used by Ember, worth creating? From 72aa1117c4d5d18116312854b4dc78c947795ba9 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Sat, 4 Jun 2016 10:59:36 -0400 Subject: [PATCH 03/23] Add call for 'How do we document this'; add that section to *this* RFC. --- text/0000-document_all_features.md | 82 ++++++++++++++++++++++++++++-- 1 file changed, 78 insertions(+), 4 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index e9c939d317b..3ff8518979c 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -3,6 +3,7 @@ - RFC PR: (leave this empty) - Rust Issue: (leave this empty) + # Summary [summary]: #summary @@ -13,7 +14,7 @@ One of the major goals of Rust's development process is *stability without stagn 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. -Although the Rust Book and Rust by Example are kept relatively up to date, [the reference is not][home-to-reference]: +Although the Rust Book and Rust by Example are kept relatively up to date, [the reference is not][home-to-reference] (on which see also the [addendum] to this RFC): > While Rust does not have a specification, the reference tries to describe its working in detail. *It tends to be out of date.* (emphasis mine) @@ -75,12 +76,40 @@ One of the main reasons not to adopt this approach, that it might block features The basic decision has led to a substantial improvement in the currency of the documentation (which is now updated the same day as a new version is released). Moreover, it has spurred ongoing development of better tooling around documentation to manage these releases. Finally, at least in the RFC author's estimation, it has also led to a substantial increase in the overall quality of that documentation, possibly as a consequence of increasing the community involvement in the documentation process (including the formation of a documentation subteam). + # Detailed design [design]: #detailed-design -The basic process of developing new language features will remain unchanged from today, with the addition of a straightforward requirement that they be properly documented before being merged to stable. +The basic process of developing new language features will remain largely the same as today. The changes are two additions: + +- a new section in the RFC, "How do we teach this?" modeled on Ember's updated RFC process +- a new requirement that the changes themselves be properly documented before being merged to stable + +## New RFC section: "How do we teach this?" +[new-rfc-section]: #new-rfc-section-how-do-we-teach-this + +Following the example of Ember.js, we will add a new section to the RFC, just after **Detailed design**, titled **How do we teach this?** The section should to 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_. + +Here is the Ember RFC section, with suggested substitutions: + +> # How We Teach This +> What names and terminology work best for these concepts and why? How is this idea best presented? As a continuation of existing ~~Ember~~ **Rust** patterns, or as a wholly new one? +> +> Would the acceptance of this proposal mean ~~Ember guides~~ **_The Rust Programing Language_, _Rust by Example_, or the Rust Reference** must be re-organized or altered? Does it change how ~~Ember~~ **Rust** is taught to new users at any level? +> +> How should this feature be introduced and taught to existing ~~Ember~~ **Rust** users? + +We may also find it valuable to add other, more Rust-specific (or programming language- rather than framework-specific) verbiage there. + +For a great example of this in practice, see the (currently open) [Ember RFC: Module Unification], which includes several sections discussing conventions, tooling, concepts, and impacts on testing. -## Language features +[Ember RFC: Module Unification]: https://github.com/dgeb/rfcs/blob/module-unification/text/0000-module-unification.md#how-we-teach-this + +## Review before stabilization + +Changes will now be reviewed for changes to the documentation prior to being merged. + +### Language features [language-features]: #language-features In the case of language features, this will be a manual process, involving updates to the `reference.md` file. (It may at some point be sensible to break up the Reference file for easier maintenance; that is left aside as orthogonal to this discussion.) @@ -95,11 +124,41 @@ This need not be especially long, but it should be long enough for ordinary user When the core team discusses whether to stabilize a feature in a given release, the reference material will now be a part of that decision. Once the feature *and* reference material are complete, it will be merged normally, and the pull request will simply include the reference material as well as the new feature. -## Standard library +### Standard library [std]: #standard-library In the case of the standard library, this could conceivably be managed by setting the `#[forbid(missing_docs)]` attribute on the library roots. In lieu of that, manual code review and general discipline should continue to serve. However, if automated tools *can* be employed here, they should. + +# How do we teach this? + +Since this RFC promotes including this section, it includes it itself. (RFCs, unlike Rust `struct` or `enum` types, may be freely self-referential. No boxing required.) + +To be most effective, this will involve some changes both at a process and core-team level, and at a community level. + +From the process and core team side of things: + +1. The RFC template should be updated to include the new section for teaching. +2. The RFC process description in the [RFCs README], specifically by including "fail to include a plan for documenting the feature" in the list of possible problems in "Submit a pull request step" in [What the process is]. +3. A blog post discussing the new process should be written discussing why we are making this change to the process, and especially explaining both the current problems and the benefits of making the change. +4. The core team should make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Core team members are already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) + +[RFCs README]: https://github.com/rust-lang/rfcs/blob/master/README.md +[What the process is]: https://github.com/rust-lang/rfcs/blob/master/README.md#what-the-process-is + +This is also an opportunity to allow/enable non-core-team members with less experience to contribute more actively to _The Rust Programming Language_, _Rust by Example_, and the Rust Reference. + +1. We should write issues for feature documentation, and flag them as approachable entry points for new users. +2. We can use the more complicated language reference issues as points for mentoring developers interested in contributing to the compiler. Helping document a complex language feature may be a useful on-ramp for working on the compiler itself. +3. We may find it useful to form a documentation subteam (under the leadership of the relevant core team representative), similar to what Ember has done, which is responsible for shepherding these changes along. + + Whether such a team is formalized or not, the goal would be for the community to take up a greater degree of responsibility for the state of the documentation, rather than it falling entirely on the shoulders of a single core team member. (Having a dedicated core team member focused solely on docs is *wonderful*, but it means we can sometimes leave it all to just one person, and Rust has far too much going on for any individual to manage on their own.) + + (See the [addendum] below, as well.) + +At a "messaging" level, we should continue to emphasize that *documentation is just as valuable as code*. For example (and there are many other similar opportunities): in addition to highlighting new language features in the release notes for each version, we might highlight any part of the documentation which saw substantial improvement in the release. + + # Drawbacks [drawbacks]: #drawbacks @@ -113,9 +172,16 @@ Finally, this may delay landing features on stable. However, all the points rais For Rust to attain its goal of *stability without stagnation*, its documentation must also be stable and not stagnant. + # Alternatives [alternatives]: #alternatives +- **Embrace the documentation, but do not include "How do we teach this?" section in new RFCs.** + + This still gives us most of the benefits (and was in fact the original form of the proposal), and does not place a new burden on RFC authors to make sure that knowing how to *teach* something is part of any new language or standard library feature. + + On the other hand, thinking about the impact on teaching should further improve consideration of the general ergonomics of a proposed feature. If something cannot be *taught* well, it's likely the design needs further refinement. + - **No change; leave RFCs as canonical documentation.** This approach can take (at least) two forms: @@ -151,3 +217,11 @@ For Rust to attain its goal of *stability without stagnation*, its documentation - Given that the reference is out of date, does it need to be brought up to date before beginning enforcement of this policy? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? - Is a documentation subteam, _a la_ the one used by Ember, worth creating? + + +# Addendum: The state of the reference +[addendum]: #addendum-the-state-of-the-reference + +Related to some of the above discussion about the current state of the reference: it may be worth creating a "strike team" to invest a couple months working on the reference: updating it, organizing it, and improving its presentation. (A single web page with *all* of this content is difficult to navigate at best.) This can proceed in parallel with the documentation of new features. It is probably a necessity for this proposal to be particularly effective in the long term. + +Once the reference is up to date, the nucleus responsible for that work may either disband or possibly (depending on the core team's evaluation of the necessity of it and the interest of the "strike team" members) become the basis of a new documentation subteam. From 92d4befb1086d72569e80ee5af50e3df00fa8443 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Sat, 4 Jun 2016 11:08:30 -0400 Subject: [PATCH 04/23] Add process for updating the reference. --- text/0000-document_all_features.md | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 3ff8518979c..161409e1672 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -14,7 +14,7 @@ One of the major goals of Rust's development process is *stability without stagn 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. -Although the Rust Book and Rust by Example are kept relatively up to date, [the reference is not][home-to-reference] (on which see also the [addendum] to this RFC): +Although the Rust Book and Rust by Example are kept relatively up to date, [the reference is not][home-to-reference]: > While Rust does not have a specification, the reference tries to describe its working in detail. *It tends to be out of date.* (emphasis mine) @@ -124,6 +124,20 @@ This need not be especially long, but it should be long enough for ordinary user When the core team discusses whether to stabilize a feature in a given release, the reference material will now be a part of that decision. Once the feature *and* reference material are complete, it will be merged normally, and the pull request will simply include the reference material as well as the new feature. +Given the current state of the reference, this may need to proceed in two steps: + +#### The current state of the reference. + +Since the reference is currently fairly out of date in a number of areas, it may be worth creating a "strike team" to invest a couple months working on the reference: updating it, organizing it, and improving its presentation. (A single web page with *all* of this content is difficult to navigate at best.) This can proceed in parallel with the documentation of new features. It is probably a necessity for this proposal to be particularly effective in the long term. + +Once the reference is up to date, the nucleus responsible for that work may either disband or possibly (depending on the core team's evaluation of the necessity of it and the interest of the "strike team" members) become the basis of a new documentation subteam. + +Updating the reference could proceed stepwise: + +1. Begin by adding an appendix in the reference with links to all accepted RFCs which have been implemented but are not yet referenced in the documentation. +2. As the reference material is written for each of those RFC features, it can be removed from that appendix. + + ### Standard library [std]: #standard-library @@ -154,8 +168,6 @@ This is also an opportunity to allow/enable non-core-team members with less expe Whether such a team is formalized or not, the goal would be for the community to take up a greater degree of responsibility for the state of the documentation, rather than it falling entirely on the shoulders of a single core team member. (Having a dedicated core team member focused solely on docs is *wonderful*, but it means we can sometimes leave it all to just one person, and Rust has far too much going on for any individual to manage on their own.) - (See the [addendum] below, as well.) - At a "messaging" level, we should continue to emphasize that *documentation is just as valuable as code*. For example (and there are many other similar opportunities): in addition to highlighting new language features in the release notes for each version, we might highlight any part of the documentation which saw substantial improvement in the release. @@ -217,11 +229,3 @@ For Rust to attain its goal of *stability without stagnation*, its documentation - Given that the reference is out of date, does it need to be brought up to date before beginning enforcement of this policy? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? - Is a documentation subteam, _a la_ the one used by Ember, worth creating? - - -# Addendum: The state of the reference -[addendum]: #addendum-the-state-of-the-reference - -Related to some of the above discussion about the current state of the reference: it may be worth creating a "strike team" to invest a couple months working on the reference: updating it, organizing it, and improving its presentation. (A single web page with *all* of this content is difficult to navigate at best.) This can proceed in parallel with the documentation of new features. It is probably a necessity for this proposal to be particularly effective in the long term. - -Once the reference is up to date, the nucleus responsible for that work may either disband or possibly (depending on the core team's evaluation of the necessity of it and the interest of the "strike team" members) become the basis of a new documentation subteam. From b2d4228621dae5a0d5eb4457d63ffcc3e3b3c704 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Sat, 4 Jun 2016 14:01:25 -0400 Subject: [PATCH 05/23] Fix some grammar issues. --- text/0000-document_all_features.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 161409e1672..cd87c0675b3 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -152,10 +152,10 @@ To be most effective, this will involve some changes both at a process and core- From the process and core team side of things: -1. The RFC template should be updated to include the new section for teaching. -2. The RFC process description in the [RFCs README], specifically by including "fail to include a plan for documenting the feature" in the list of possible problems in "Submit a pull request step" in [What the process is]. -3. A blog post discussing the new process should be written discussing why we are making this change to the process, and especially explaining both the current problems and the benefits of making the change. -4. The core team should make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Core team members are already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) +1. Update the RFC template to include the new section for teaching. +2. Update the RFC process description in the [RFCs README], specifically by including "fail to include a plan for documenting the feature" in the list of possible problems in "Submit a pull request step" in [What the process is]. +3. Write a blog post discussing the new process should be written discussing why we are making this change to the process, and especially explaining both the current problems and the benefits of making the change. +4. Make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Core team members are already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) [RFCs README]: https://github.com/rust-lang/rfcs/blob/master/README.md [What the process is]: https://github.com/rust-lang/rfcs/blob/master/README.md#what-the-process-is From fc2718cc35be7f7e90cd619850872f2160d25c19 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Mon, 6 Jun 2016 14:22:52 -0400 Subject: [PATCH 06/23] Fix bad reference-style link. --- text/0000-document_all_features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index cd87c0675b3..4609193b18c 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -62,11 +62,11 @@ This exact idea has been adopted by the Ember community after their somewhat bum [@davidgoli]: https://github.com/emberjs/rfcs/pull/56#issuecomment-114635962 -The Ember core team agreed, and embraced the principle outlined in [this comment][guarav0]: +The Ember core team agreed, and embraced the principle outlined in [this comment][@guarav0]: > No version shall be released until guides and versioned API documentation is ready. This will allow newcomers the ability to understand the latest release. ([@guarav0]) -[guarav0]: https://github.com/emberjs/rfcs/pull/56#issuecomment-114339423 +[@guarav0]: https://github.com/emberjs/rfcs/pull/56#issuecomment-114339423 One of the main reasons not to adopt this approach, that it might block features from landing as soon as they otherwise might, was [addressed][@eccegordo] in that discussion as well: From 8e1b6da3fded59015a38f3cb8c4ec52c4c98b4ad Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 7 Jun 2016 19:04:16 -0400 Subject: [PATCH 07/23] Add a number of further considerations. --- text/0000-document_all_features.md | 74 ++++++++++++++++++++++++++---- 1 file changed, 66 insertions(+), 8 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 4609193b18c..8e0358d2864 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -83,6 +83,7 @@ The basic decision has led to a substantial improvement in the currency of the d The basic process of developing new language features will remain largely the same as today. The changes are two additions: - a new section in the RFC, "How do we teach this?" modeled on Ember's updated RFC process + - a new requirement that the changes themselves be properly documented before being merged to stable ## New RFC section: "How do we teach this?" @@ -135,8 +136,8 @@ Once the reference is up to date, the nucleus responsible for that work may eith Updating the reference could proceed stepwise: 1. Begin by adding an appendix in the reference with links to all accepted RFCs which have been implemented but are not yet referenced in the documentation. -2. As the reference material is written for each of those RFC features, it can be removed from that appendix. +2. As the reference material is written for each of those RFC features, it can be removed from that appendix. ### Standard library [std]: #standard-library @@ -144,6 +145,28 @@ Updating the reference could proceed stepwise: In the case of the standard library, this could conceivably be managed by setting the `#[forbid(missing_docs)]` attribute on the library roots. In lieu of that, manual code review and general discipline should continue to serve. However, if automated tools *can* be employed here, they should. +## Add an "Edit" link +[edit-link]: #add-an-edit-link + +To support its own change, the Ember team added an "edit this" icon to the top of every page in the guides (and plans to do so for the API documentation, pending infrastructure changes to support that). Each of _The Rust Programming Language_, _Rust by Example_, and the Rust Reference should do the same. + +Making a similar change has some downsides (see below under [**Drawbacks**][drawbacks]), but it has two major upsides: + +1. It gives users an obvious action to fix typos. Speaking from personal experience, it can be difficult to find where a given documentation or book page exists in the Rust repository. Even with the drawbacks noted below, this would substantially smooth the process of making e.g. a small typo fix for first-time readers of _The Rust Programming Language_. Making the first contribution easy makes further contributions much more likely. + +2. It sends a quiet but real signal that the docs are up for editing. This makes it likelier that people will edit them! + +### Optional: Support with infrastructure change +[edit-link-infrastructure]: #optional-support-with-infrastructure-change + +The links to edit the documentation could track against the release branch instead of against `master`. (Fixes to documentation would be analogous to bugfix releases in this sense.) Targeting the pull-request automatically would be straightforward. However, see below under [**Drawbacks**][drawbacks]. + +## Optional: Visually Distinguish Nightly +[distinguish-nightly]: #optional-visually-distinguish-nightly + +It might be useful to visually distinguish the documentation for nightly Rust as being unstable and subject to change, even simply by setting a different default theme on _The Rust Programming Language_ book for nightly Rust. + + # How do we teach this? Since this RFC promotes including this section, it includes it itself. (RFCs, unlike Rust `struct` or `enum` types, may be freely self-referential. No boxing required.) @@ -153,8 +176,11 @@ To be most effective, this will involve some changes both at a process and core- From the process and core team side of things: 1. Update the RFC template to include the new section for teaching. + 2. Update the RFC process description in the [RFCs README], specifically by including "fail to include a plan for documenting the feature" in the list of possible problems in "Submit a pull request step" in [What the process is]. + 3. Write a blog post discussing the new process should be written discussing why we are making this change to the process, and especially explaining both the current problems and the benefits of making the change. + 4. Make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Core team members are already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) [RFCs README]: https://github.com/rust-lang/rfcs/blob/master/README.md @@ -163,10 +189,12 @@ From the process and core team side of things: This is also an opportunity to allow/enable non-core-team members with less experience to contribute more actively to _The Rust Programming Language_, _Rust by Example_, and the Rust Reference. 1. We should write issues for feature documentation, and flag them as approachable entry points for new users. + 2. We can use the more complicated language reference issues as points for mentoring developers interested in contributing to the compiler. Helping document a complex language feature may be a useful on-ramp for working on the compiler itself. -3. We may find it useful to form a documentation subteam (under the leadership of the relevant core team representative), similar to what Ember has done, which is responsible for shepherding these changes along. - Whether such a team is formalized or not, the goal would be for the community to take up a greater degree of responsibility for the state of the documentation, rather than it falling entirely on the shoulders of a single core team member. (Having a dedicated core team member focused solely on docs is *wonderful*, but it means we can sometimes leave it all to just one person, and Rust has far too much going on for any individual to manage on their own.) +3. ~~We may find it useful to form~~ We are already forming a documentation subteam (under the leadership of the relevant core team representative), similar to what Ember has done, which will be responsible for shepherding these changes along. + + ~~Whether such a team is formalized or not,~~ Even with such a team in place, a major goal remains encouraging the community to take up a greater degree of responsibility for the state of the documentation, rather than it falling entirely on the shoulders of a single core team member or even the docs team. (Having a dedicated core team member focused solely on docs is *wonderful*, but it means we can sometimes leave it all to just one person, and Rust has far too much going on for any individual to manage on their own.) At a "messaging" level, we should continue to emphasize that *documentation is just as valuable as code*. For example (and there are many other similar opportunities): in addition to highlighting new language features in the release notes for each version, we might highlight any part of the documentation which saw substantial improvement in the release. @@ -174,20 +202,47 @@ At a "messaging" level, we should continue to emphasize that *documentation is j # Drawbacks [drawbacks]: #drawbacks -The largest drawback at present is that the language reference is *already* quite out of date. It may take substantial work to get it up to date so that new changes can be landed appropriately. (Arguably, however, this should be done regardless, since the language reference is an important part of the language ecosystem.) +1. The largest drawback at present is that the language reference is *already* quite out of date. It may take substantial work to get it up to date so that new changes can be landed appropriately. (Arguably, however, this should be done regardless, since the language reference is an important part of the language ecosystem.) + +2. Another potential issue is that some sections of the reference are particularly thorny and must be handled with considerable care (e.g. lifetimes). Although in general it would not be necessary for the author of the new language feature to write all the documentation, considerable extra care and oversight would need to be in place for these sections. + +3. This may delay landing features on stable. However, all the points raised in [**Precedent**][precedent] on this apply, especially: + + > We can't get the great new toys unless everybody can enjoy the toys. ([@eccegordo]) + + For Rust to attain its goal of *stability without stagnation*, its documentation must also be stable and not stagnant. + +4. If the forthcoming docs team is unable to provide significant support for the core team member responsible for documentation, and perhaps equally if the rest of the community does not also increase involvement, this will simply not work. No individual can manage all of these docs alone. + +5. Specific to the suggestion to [**Add an "edit" link**][edit-link]: -Another potential issue is that some sections of the reference are particularly thorny and must be handled with considerable care (e.g. lifetimes). Although in general it would not be necessary for the author of the new language feature to write all the documentation, considerable extra care and oversight would need to be in place for these sections. + - If the specific page is in flux (e.g. being rewritten, broken into pieces, etc.), then a link to edit `master` will be confusing. + - In addition, when users *have* made edits, it may take some time before it appears, and thus users may be confused when attempting to make edits and finding that the relevant editss have already been made. + - Some pages users attempt to edit are *likely* to have different documentation in them than the existing pages, to account for inbound changes for feature additions to the language! -Finally, this may delay landing features on stable. However, all the points raised in [**Precedent**][precedent] on this apply, especially: + Two notes, however: -> We can't get the great new toys unless everybody can enjoy the toys. ([@eccegordo]) + 1. Even facing the same issues, the Ember team has found it useful to have the link, as it enables basically any user of a sufficient comfort level with GitHub to fix basic typos or logic errors. + 2. This concern primarily impacts _The Rust Programming Language_. Both in its current state and in the event of an eventual revamp (at least: after such a revamp finished), the Rust Reference is far less likely to see pages removed or moved. -For Rust to attain its goal of *stability without stagnation*, its documentation must also be stable and not stagnant. + Finally, while infrastructure changes could be made in support of a more "targeted" editing experience, doing so would substantially increase the triage work required for the docs. It would also entail extra work "porting" the changes back to `master`. Additionally, because the language itself does not currently "bugfix" releases, this would substantially alter the workflow for dealing with releases in general. + +6. Specific to the suggestion to [**Visually Distinguish Nightly**][distinguish-nightly]: + + This requires at least some infrastructure investment. Making the change apply to the Reference as well as to the two books would entail the maintenance of further CSS. This might be acceptable if documentation teams are sufficiently motivated and engaged, but it means that if not very carefully designed up front, any changes to the documentation theme will basically require double CSS changes; they will also require double the *design* efforts. # Alternatives [alternatives]: #alternatives +- **Just add the "How do we teach this?" section.** + + Of all the alternatives, this is the easiest (and probably the best). It does not substantially change the state with regard to the documentation, and even having the section in the RFC does not mean that it will end up added to the docs, as evidence by the [`#[deprecated]` RFC][RFC 1270], which included as part of its text: + + > The language reference will be extended to describe this feature as outlined in this RFC. Authors shall be advised to leave their users enough time to react before removing a deprecated item. + + This is not a small downside by any stretch—but adding the section to the RFC will still have all the secondary benefits noted above, and it probably at least somewhat increases the likelihood that new features do get documented. + - **Embrace the documentation, but do not include "How do we teach this?" section in new RFCs.** This still gives us most of the benefits (and was in fact the original form of the proposal), and does not place a new burden on RFC authors to make sure that knowing how to *teach* something is part of any new language or standard library feature. @@ -222,9 +277,12 @@ For Rust to attain its goal of *stability without stagnation*, its documentation The main downside, of course, is that this would leave very large swaths of the language basically without *any* documentation, and even more of it only documented in RFCs than is the case today. +[RFC 1270]: https://github.com/rust-lang/rfcs/pull/1270 + # Unresolved questions [unresolved]: #unresolved-questions +- How do we clearly distinguish between features on nightly, beta, and stable Rust—in the reference especially, but also in the book? - How will the requirement for documentation in the reference be enforced? - Given that the reference is out of date, does it need to be brought up to date before beginning enforcement of this policy? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? From cf5513e6c3dd59b7f3f3237f5065a3015e52e4c6 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 9 Aug 2016 11:18:41 -0400 Subject: [PATCH 08/23] Add outline, clarify document structure. --- text/0000-document_all_features.md | 54 ++++++++++++++++++++++++++---- 1 file changed, 48 insertions(+), 6 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 8e0358d2864..d8ad6bdcc52 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -9,6 +9,33 @@ One of the major goals of Rust's development process is *stability without stagnation*. That means we add features regularly. However, it can be difficult to *use* those features if they are not publicly documented anywhere. Therefore, this RFC proposes requiring that all new language features and public standard library items must be documented before landing on the stable release branch (item documentation for the standard library; in the language reference for language features). + +## Outline +[outline]: #outline + +- [Summary](#summary) + - [Outline](#outline) +- [Motivation](#motivation) + - [The Current Situation](#the-current-situation) + - [Precedent](#precedent) +- [Detailed design](#detailed-design) + - [New RFC section: “How do we teach + this?”](#new-rfc-section-how-do-we-teach-this) + - [New requirement to document changes before + stabilizing](#new-requirement-to-document-changes-before-stabilizing) + - [Language features](#language-features) + - [Standard library](#standard-library) + - [Add an “Edit” link (optional)](#add-an-edit-link-optional) + - [Support with infrastructure + change](#support-with-infrastructure-change) + - [Visually Distinguish + Nightly (optional)](#visually-distinguish-nightly-optional) +- [How do we teach this?](#how-do-we-teach-this) +- [Drawbacks](#drawbacks) +- [Alternatives](#alternatives) +- [Unresolved questions](#unresolved-questions) + + # Motivation [motivation]: #motivation @@ -86,6 +113,12 @@ The basic process of developing new language features will remain largely the sa - a new requirement that the changes themselves be properly documented before being merged to stable +Additionally, we might make some content-level/infrastructural changes: + +- add an "edit" link to the documentation pages +- visually distinguish nightly vs. stable build docs + + ## New RFC section: "How do we teach this?" [new-rfc-section]: #new-rfc-section-how-do-we-teach-this @@ -106,14 +139,22 @@ For a great example of this in practice, see the (currently open) [Ember RFC: Mo [Ember RFC: Module Unification]: https://github.com/dgeb/rfcs/blob/module-unification/text/0000-module-unification.md#how-we-teach-this -## Review before stabilization +## New requirement to document changes before stabilizing -Changes will now be reviewed for changes to the documentation prior to being merged. +Changes will now be reviewed for changes to the documentation prior to being merged. This will proceed in the following places: + +- language features: + - in the reference + - in _The Rust Programming Language_ + - in _Rust by Example_ +- the standard library: in the `std` API docs ### Language features [language-features]: #language-features -In the case of language features, this will be a manual process, involving updates to the `reference.md` file. (It may at some point be sensible to break up the Reference file for easier maintenance; that is left aside as orthogonal to this discussion.) +We will document *all* language features in the Rust Reference, as well as making some updates to _The Rust Programming Language_ and _Rust by Example_ as necessary. + +This will necessarily be a manual process, involving updates to the `reference.md` file. (It may at some point be sensible to break up the Reference file for easier maintenance; that is left aside as orthogonal to this discussion.) Note that the feature documentation does not need to be written by the feature author. In fact, this is one of the areas where the community may be most able to support core developers even if not themselves programming language theorists or compiler hackers. This may free up the compiler developers' time. It will also help communicate the features in a way that is accessible to ordinary Rust users. @@ -128,6 +169,7 @@ When the core team discusses whether to stabilize a feature in a given release, Given the current state of the reference, this may need to proceed in two steps: #### The current state of the reference. +[refstate]: #the-current-state-of-the-reference Since the reference is currently fairly out of date in a number of areas, it may be worth creating a "strike team" to invest a couple months working on the reference: updating it, organizing it, and improving its presentation. (A single web page with *all* of this content is difficult to navigate at best.) This can proceed in parallel with the documentation of new features. It is probably a necessity for this proposal to be particularly effective in the long term. @@ -145,7 +187,7 @@ Updating the reference could proceed stepwise: In the case of the standard library, this could conceivably be managed by setting the `#[forbid(missing_docs)]` attribute on the library roots. In lieu of that, manual code review and general discipline should continue to serve. However, if automated tools *can* be employed here, they should. -## Add an "Edit" link +## Add an "Edit" link (optional) [edit-link]: #add-an-edit-link To support its own change, the Ember team added an "edit this" icon to the top of every page in the guides (and plans to do so for the API documentation, pending infrastructure changes to support that). Each of _The Rust Programming Language_, _Rust by Example_, and the Rust Reference should do the same. @@ -156,12 +198,12 @@ Making a similar change has some downsides (see below under [**Drawbacks**][draw 2. It sends a quiet but real signal that the docs are up for editing. This makes it likelier that people will edit them! -### Optional: Support with infrastructure change +### Support with infrastructure change [edit-link-infrastructure]: #optional-support-with-infrastructure-change The links to edit the documentation could track against the release branch instead of against `master`. (Fixes to documentation would be analogous to bugfix releases in this sense.) Targeting the pull-request automatically would be straightforward. However, see below under [**Drawbacks**][drawbacks]. -## Optional: Visually Distinguish Nightly +## Visually Distinguish Nightly (optional) [distinguish-nightly]: #optional-visually-distinguish-nightly It might be useful to visually distinguish the documentation for nightly Rust as being unstable and subject to change, even simply by setting a different default theme on _The Rust Programming Language_ book for nightly Rust. From d04dfa6dc1667fa5d580a9d8bbca9a80c639b617 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 20 Sep 2016 20:06:02 -0400 Subject: [PATCH 09/23] Address concerns about documentation infrastructure. --- text/0000-document_all_features.md | 23 ++--------------------- 1 file changed, 2 insertions(+), 21 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index d8ad6bdcc52..d3123f5c444 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -26,10 +26,6 @@ One of the major goals of Rust's development process is *stability without stagn - [Language features](#language-features) - [Standard library](#standard-library) - [Add an “Edit” link (optional)](#add-an-edit-link-optional) - - [Support with infrastructure - change](#support-with-infrastructure-change) - - [Visually Distinguish - Nightly (optional)](#visually-distinguish-nightly-optional) - [How do we teach this?](#how-do-we-teach-this) - [Drawbacks](#drawbacks) - [Alternatives](#alternatives) @@ -107,16 +103,15 @@ The basic decision has led to a substantial improvement in the currency of the d # Detailed design [design]: #detailed-design -The basic process of developing new language features will remain largely the same as today. The changes are two additions: +The basic process of developing new language features will remain largely the same as today. The required changes are two additions: - a new section in the RFC, "How do we teach this?" modeled on Ember's updated RFC process - a new requirement that the changes themselves be properly documented before being merged to stable -Additionally, we might make some content-level/infrastructural changes: +Additionally, we should make some content-level/infrastructural changes: - add an "edit" link to the documentation pages -- visually distinguish nightly vs. stable build docs ## New RFC section: "How do we teach this?" @@ -198,16 +193,6 @@ Making a similar change has some downsides (see below under [**Drawbacks**][draw 2. It sends a quiet but real signal that the docs are up for editing. This makes it likelier that people will edit them! -### Support with infrastructure change -[edit-link-infrastructure]: #optional-support-with-infrastructure-change - -The links to edit the documentation could track against the release branch instead of against `master`. (Fixes to documentation would be analogous to bugfix releases in this sense.) Targeting the pull-request automatically would be straightforward. However, see below under [**Drawbacks**][drawbacks]. - -## Visually Distinguish Nightly (optional) -[distinguish-nightly]: #optional-visually-distinguish-nightly - -It might be useful to visually distinguish the documentation for nightly Rust as being unstable and subject to change, even simply by setting a different default theme on _The Rust Programming Language_ book for nightly Rust. - # How do we teach this? @@ -269,10 +254,6 @@ At a "messaging" level, we should continue to emphasize that *documentation is j Finally, while infrastructure changes could be made in support of a more "targeted" editing experience, doing so would substantially increase the triage work required for the docs. It would also entail extra work "porting" the changes back to `master`. Additionally, because the language itself does not currently "bugfix" releases, this would substantially alter the workflow for dealing with releases in general. -6. Specific to the suggestion to [**Visually Distinguish Nightly**][distinguish-nightly]: - - This requires at least some infrastructure investment. Making the change apply to the Reference as well as to the two books would entail the maintenance of further CSS. This might be acceptable if documentation teams are sufficiently motivated and engaged, but it means that if not very carefully designed up front, any changes to the documentation theme will basically require double CSS changes; they will also require double the *design* efforts. - # Alternatives [alternatives]: #alternatives From 297e5b19231a54e83b247403b4bb24c01f1d13db Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 20 Sep 2016 20:12:23 -0400 Subject: [PATCH 10/23] =?UTF-8?q?Address=20concern=20about=20=E2=80=9Cedit?= =?UTF-8?q?=20link".?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- text/0000-document_all_features.md | 30 ------------------------------ 1 file changed, 30 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index d3123f5c444..f830356bda8 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -25,7 +25,6 @@ One of the major goals of Rust's development process is *stability without stagn stabilizing](#new-requirement-to-document-changes-before-stabilizing) - [Language features](#language-features) - [Standard library](#standard-library) - - [Add an “Edit” link (optional)](#add-an-edit-link-optional) - [How do we teach this?](#how-do-we-teach-this) - [Drawbacks](#drawbacks) - [Alternatives](#alternatives) @@ -109,10 +108,6 @@ The basic process of developing new language features will remain largely the sa - a new requirement that the changes themselves be properly documented before being merged to stable -Additionally, we should make some content-level/infrastructural changes: - -- add an "edit" link to the documentation pages - ## New RFC section: "How do we teach this?" [new-rfc-section]: #new-rfc-section-how-do-we-teach-this @@ -182,18 +177,6 @@ Updating the reference could proceed stepwise: In the case of the standard library, this could conceivably be managed by setting the `#[forbid(missing_docs)]` attribute on the library roots. In lieu of that, manual code review and general discipline should continue to serve. However, if automated tools *can* be employed here, they should. -## Add an "Edit" link (optional) -[edit-link]: #add-an-edit-link - -To support its own change, the Ember team added an "edit this" icon to the top of every page in the guides (and plans to do so for the API documentation, pending infrastructure changes to support that). Each of _The Rust Programming Language_, _Rust by Example_, and the Rust Reference should do the same. - -Making a similar change has some downsides (see below under [**Drawbacks**][drawbacks]), but it has two major upsides: - -1. It gives users an obvious action to fix typos. Speaking from personal experience, it can be difficult to find where a given documentation or book page exists in the Rust repository. Even with the drawbacks noted below, this would substantially smooth the process of making e.g. a small typo fix for first-time readers of _The Rust Programming Language_. Making the first contribution easy makes further contributions much more likely. - -2. It sends a quiet but real signal that the docs are up for editing. This makes it likelier that people will edit them! - - # How do we teach this? Since this RFC promotes including this section, it includes it itself. (RFCs, unlike Rust `struct` or `enum` types, may be freely self-referential. No boxing required.) @@ -241,19 +224,6 @@ At a "messaging" level, we should continue to emphasize that *documentation is j 4. If the forthcoming docs team is unable to provide significant support for the core team member responsible for documentation, and perhaps equally if the rest of the community does not also increase involvement, this will simply not work. No individual can manage all of these docs alone. -5. Specific to the suggestion to [**Add an "edit" link**][edit-link]: - - - If the specific page is in flux (e.g. being rewritten, broken into pieces, etc.), then a link to edit `master` will be confusing. - - In addition, when users *have* made edits, it may take some time before it appears, and thus users may be confused when attempting to make edits and finding that the relevant editss have already been made. - - Some pages users attempt to edit are *likely* to have different documentation in them than the existing pages, to account for inbound changes for feature additions to the language! - - Two notes, however: - - 1. Even facing the same issues, the Ember team has found it useful to have the link, as it enables basically any user of a sufficient comfort level with GitHub to fix basic typos or logic errors. - 2. This concern primarily impacts _The Rust Programming Language_. Both in its current state and in the event of an eventual revamp (at least: after such a revamp finished), the Rust Reference is far less likely to see pages removed or moved. - - Finally, while infrastructure changes could be made in support of a more "targeted" editing experience, doing so would substantially increase the triage work required for the docs. It would also entail extra work "porting" the changes back to `master`. Additionally, because the language itself does not currently "bugfix" releases, this would substantially alter the workflow for dealing with releases in general. - # Alternatives [alternatives]: #alternatives From 2bfd6fd060fb55bf0e68bfb984b0f85eea957f8f Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 20 Sep 2016 20:12:48 -0400 Subject: [PATCH 11/23] Add note on book rewrite status. --- text/0000-document_all_features.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index f830356bda8..3f25d08d83a 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -278,5 +278,6 @@ At a "messaging" level, we should continue to emphasize that *documentation is j - How do we clearly distinguish between features on nightly, beta, and stable Rust—in the reference especially, but also in the book? - How will the requirement for documentation in the reference be enforced? - Given that the reference is out of date, does it need to be brought up to date before beginning enforcement of this policy? +- Given that the book is in the process of a rewrite for print publication, how shall we apply this requirement to RFCs merged during its development? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? - Is a documentation subteam, _a la_ the one used by Ember, worth creating? From 19cf3a3f7df23ce80164e0877e3fd268ceefbf12 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 20 Sep 2016 20:16:52 -0400 Subject: [PATCH 12/23] Address concern: unclear language about change reviews. --- text/0000-document_all_features.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 3f25d08d83a..e39ac399c58 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -131,7 +131,7 @@ For a great example of this in practice, see the (currently open) [Ember RFC: Mo ## New requirement to document changes before stabilizing -Changes will now be reviewed for changes to the documentation prior to being merged. This will proceed in the following places: +Prior to approving pull requests that stabilize features, reviewers must verify that the document is properly documented in the following places: - language features: - in the reference From 8e145aeab82c057458daf578e2aeee2ab3e24151 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 20 Sep 2016 20:21:17 -0400 Subject: [PATCH 13/23] Address concern: remove blog post requirement. --- text/0000-document_all_features.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index e39ac399c58..a73a981f1cd 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -189,9 +189,7 @@ From the process and core team side of things: 2. Update the RFC process description in the [RFCs README], specifically by including "fail to include a plan for documenting the feature" in the list of possible problems in "Submit a pull request step" in [What the process is]. -3. Write a blog post discussing the new process should be written discussing why we are making this change to the process, and especially explaining both the current problems and the benefits of making the change. - -4. Make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Core team members are already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) +3. Make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Core team members are already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) [RFCs README]: https://github.com/rust-lang/rfcs/blob/master/README.md [What the process is]: https://github.com/rust-lang/rfcs/blob/master/README.md#what-the-process-is From d04b8c31254b263a55636e2c8ae63690537e4746 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 20 Sep 2016 20:21:51 -0400 Subject: [PATCH 14/23] Address concern: needless inline strikeouts. --- text/0000-document_all_features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index a73a981f1cd..290e4038114 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -200,9 +200,9 @@ This is also an opportunity to allow/enable non-core-team members with less expe 2. We can use the more complicated language reference issues as points for mentoring developers interested in contributing to the compiler. Helping document a complex language feature may be a useful on-ramp for working on the compiler itself. -3. ~~We may find it useful to form~~ We are already forming a documentation subteam (under the leadership of the relevant core team representative), similar to what Ember has done, which will be responsible for shepherding these changes along. +3. We have formed a documentation subteam (under the leadership of the relevant core team representative), similar to what Ember has done, which will be responsible for shepherding these changes along. - ~~Whether such a team is formalized or not,~~ Even with such a team in place, a major goal remains encouraging the community to take up a greater degree of responsibility for the state of the documentation, rather than it falling entirely on the shoulders of a single core team member or even the docs team. (Having a dedicated core team member focused solely on docs is *wonderful*, but it means we can sometimes leave it all to just one person, and Rust has far too much going on for any individual to manage on their own.) + Even with such a team in place, a major goal remains encouraging the community to take up a greater degree of responsibility for the state of the documentation, rather than it falling entirely on the shoulders of a single core team member or even the docs team. (Having a dedicated core team member focused solely on docs is *wonderful*, but it means we can sometimes leave it all to just one person, and Rust has far too much going on for any individual to manage on their own.) At a "messaging" level, we should continue to emphasize that *documentation is just as valuable as code*. For example (and there are many other similar opportunities): in addition to highlighting new language features in the release notes for each version, we might highlight any part of the documentation which saw substantial improvement in the release. From 3f8ed2022afe5749dfa41ead4de5d37a57f91e66 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Tue, 20 Sep 2016 20:25:18 -0400 Subject: [PATCH 15/23] =?UTF-8?q?Address=20concern:=20unnecessary=20refere?= =?UTF-8?q?nces=20to=20=E2=80=9Ccore=20team=E2=80=9D.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- text/0000-document_all_features.md | 16 +++++----------- 1 file changed, 5 insertions(+), 11 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 290e4038114..560e0edf69d 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -154,7 +154,7 @@ Instead, the documentation process should immediately precede the move to stabil This need not be especially long, but it should be long enough for ordinary users to learn how to use the language feature *without reading the RFCs*. -When the core team discusses whether to stabilize a feature in a given release, the reference material will now be a part of that decision. Once the feature *and* reference material are complete, it will be merged normally, and the pull request will simply include the reference material as well as the new feature. +When the discussing whether to stabilize a feature in a given release, the reference material will now be a part of that decision. Once the feature *and* reference material are complete, it will be merged normally, and the pull request will simply include the reference material as well as the new feature. Given the current state of the reference, this may need to proceed in two steps: @@ -183,13 +183,11 @@ Since this RFC promotes including this section, it includes it itself. (RFCs, un To be most effective, this will involve some changes both at a process and core-team level, and at a community level. -From the process and core team side of things: +1. The RFC template must be updated to include the new section for teaching. -1. Update the RFC template to include the new section for teaching. +2. The RFC process in the [RFCs README] must be updated, specifically by including "fail to include a plan for documenting the feature" in the list of possible problems in "Submit a pull request step" in [What the process is]. -2. Update the RFC process description in the [RFCs README], specifically by including "fail to include a plan for documenting the feature" in the list of possible problems in "Submit a pull request step" in [What the process is]. - -3. Make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Core team members are already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) +3. Make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Much of the community is already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) [RFCs README]: https://github.com/rust-lang/rfcs/blob/master/README.md [What the process is]: https://github.com/rust-lang/rfcs/blob/master/README.md#what-the-process-is @@ -200,10 +198,6 @@ This is also an opportunity to allow/enable non-core-team members with less expe 2. We can use the more complicated language reference issues as points for mentoring developers interested in contributing to the compiler. Helping document a complex language feature may be a useful on-ramp for working on the compiler itself. -3. We have formed a documentation subteam (under the leadership of the relevant core team representative), similar to what Ember has done, which will be responsible for shepherding these changes along. - - Even with such a team in place, a major goal remains encouraging the community to take up a greater degree of responsibility for the state of the documentation, rather than it falling entirely on the shoulders of a single core team member or even the docs team. (Having a dedicated core team member focused solely on docs is *wonderful*, but it means we can sometimes leave it all to just one person, and Rust has far too much going on for any individual to manage on their own.) - At a "messaging" level, we should continue to emphasize that *documentation is just as valuable as code*. For example (and there are many other similar opportunities): in addition to highlighting new language features in the release notes for each version, we might highlight any part of the documentation which saw substantial improvement in the release. @@ -220,7 +214,7 @@ At a "messaging" level, we should continue to emphasize that *documentation is j For Rust to attain its goal of *stability without stagnation*, its documentation must also be stable and not stagnant. -4. If the forthcoming docs team is unable to provide significant support for the core team member responsible for documentation, and perhaps equally if the rest of the community does not also increase involvement, this will simply not work. No individual can manage all of these docs alone. +4. If the forthcoming docs team is unable to provide significant support, and perhaps equally if the rest of the community does not also increase involvement, this will simply not work. No individual can manage all of these docs alone. # Alternatives From d4a0fba44e98f3965a68221b299bc0cb45e87ea8 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Wed, 19 Oct 2016 11:36:18 -0400 Subject: [PATCH 16/23] Clarify must/should/may around the books. Require release notes. --- text/0000-document_all_features.md | 69 +++++++++++++++--------------- 1 file changed, 34 insertions(+), 35 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 560e0edf69d..e270a421334 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -19,10 +19,8 @@ One of the major goals of Rust's development process is *stability without stagn - [The Current Situation](#the-current-situation) - [Precedent](#precedent) - [Detailed design](#detailed-design) - - [New RFC section: “How do we teach - this?”](#new-rfc-section-how-do-we-teach-this) - - [New requirement to document changes before - stabilizing](#new-requirement-to-document-changes-before-stabilizing) + - [New RFC section: “How do we teach this?”](#new-rfc-section-how-do-we-teach-this) + - [New requirement to document changes before stabilizing](#new-requirement-to-document-changes-before-stabilizing) - [Language features](#language-features) - [Standard library](#standard-library) - [How do we teach this?](#how-do-we-teach-this) @@ -131,13 +129,16 @@ For a great example of this in practice, see the (currently open) [Ember RFC: Mo ## New requirement to document changes before stabilizing -Prior to approving pull requests that stabilize features, reviewers must verify that the document is properly documented in the following places: +Prior to stabilizing a feature, the features will now be documented as follows: -- language features: - - in the reference - - in _The Rust Programming Language_ - - in _Rust by Example_ -- the standard library: in the `std` API docs +- Language features: + - must be documented in the 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. ### Language features [language-features]: #language-features @@ -146,7 +147,7 @@ We will document *all* language features in the Rust Reference, as well as makin This will necessarily be a manual process, involving updates to the `reference.md` file. (It may at some point be sensible to break up the Reference file for easier maintenance; that is left aside as orthogonal to this discussion.) -Note that the feature documentation does not need to be written by the feature author. In fact, this is one of the areas where the community may be most able to support core developers even if not themselves programming language theorists or compiler hackers. This may free up the compiler developers' time. It will also help communicate the features in a way that is accessible to ordinary Rust users. +Note that the feature documentation does not need to be written by the feature author. In fact, this is one of the areas where the community may be most able to support the language/compiler developers even if not themselves programming language theorists or compiler hackers. This may free up the compiler developers' time. It will also help communicate the features in a way that is accessible to ordinary Rust users. New features do not need to be documented to be merged into `master`/nightly, and in many cases *should* not, since the features may change substantially before landing on stable, at which point the reference material would need to be rewritten. @@ -184,9 +185,7 @@ Since this RFC promotes including this section, it includes it itself. (RFCs, un To be most effective, this will involve some changes both at a process and core-team level, and at a community level. 1. The RFC template must be updated to include the new section for teaching. - 2. The RFC process in the [RFCs README] must be updated, specifically by including "fail to include a plan for documenting the feature" in the list of possible problems in "Submit a pull request step" in [What the process is]. - 3. Make documentation and teachability of new features *equally* high priority with the features themselves, and communicate this clearly in discussion of the features. (Much of the community is already very good about including this in considerations of language design; this simply makes this an explicit goal of discussions around RFCs.) [RFCs README]: https://github.com/rust-lang/rfcs/blob/master/README.md @@ -194,9 +193,9 @@ To be most effective, this will involve some changes both at a process and core- This is also an opportunity to allow/enable non-core-team members with less experience to contribute more actively to _The Rust Programming Language_, _Rust by Example_, and the Rust Reference. -1. We should write issues for feature documentation, and flag them as approachable entry points for new users. +1. We should write issues for feature documentation, and may flag them as approachable entry points for new users. -2. We can use the more complicated language reference issues as points for mentoring developers interested in contributing to the compiler. Helping document a complex language feature may be a useful on-ramp for working on the compiler itself. +2. We may use the more complicated language reference issues as points for mentoring developers interested in contributing to the compiler. Helping document a complex language feature may be a useful on-ramp for working on the compiler itself. At a "messaging" level, we should continue to emphasize that *documentation is just as valuable as code*. For example (and there are many other similar opportunities): in addition to highlighting new language features in the release notes for each version, we might highlight any part of the documentation which saw substantial improvement in the release. @@ -204,62 +203,62 @@ At a "messaging" level, we should continue to emphasize that *documentation is j # Drawbacks [drawbacks]: #drawbacks -1. The largest drawback at present is that the language reference is *already* quite out of date. It may take substantial work to get it up to date so that new changes can be landed appropriately. (Arguably, however, this should be done regardless, since the language reference is an important part of the language ecosystem.) +1. The largest drawback at present is that the language reference is *already* quite out of date. It may take substantial work to get it up to date so that new changes can be landed appropriately. (Arguably, however, this should be done regardless, since the language reference is an important part of the language ecosystem.) -2. Another potential issue is that some sections of the reference are particularly thorny and must be handled with considerable care (e.g. lifetimes). Although in general it would not be necessary for the author of the new language feature to write all the documentation, considerable extra care and oversight would need to be in place for these sections. +2. Another potential issue is that some sections of the reference are particularly thorny and must be handled with considerable care (e.g. lifetimes). Although in general it would not be necessary for the author of the new language feature to write all the documentation, considerable extra care and oversight would need to be in place for these sections. -3. This may delay landing features on stable. However, all the points raised in [**Precedent**][precedent] on this apply, especially: +3. This may delay landing features on stable. However, all the points raised in [**Precedent**][precedent] on this apply, especially: > We can't get the great new toys unless everybody can enjoy the toys. ([@eccegordo]) For Rust to attain its goal of *stability without stagnation*, its documentation must also be stable and not stagnant. -4. If the forthcoming docs team is unable to provide significant support, and perhaps equally if the rest of the community does not also increase involvement, this will simply not work. No individual can manage all of these docs alone. +4. If the forthcoming docs team is unable to provide significant support, and perhaps equally if the rest of the community does not also increase involvement, this will simply not work. No individual can manage all of these docs alone. # Alternatives [alternatives]: #alternatives -- **Just add the "How do we teach this?" section.** +- **Just add the "How do we teach this?" section.** - Of all the alternatives, this is the easiest (and probably the best). It does not substantially change the state with regard to the documentation, and even having the section in the RFC does not mean that it will end up added to the docs, as evidence by the [`#[deprecated]` RFC][RFC 1270], which included as part of its text: + Of all the alternatives, this is the easiest (and probably the best). It does not substantially change the state with regard to the documentation, and even having the section in the RFC does not mean that it will end up added to the docs, as evidence by the [`#[deprecated]` RFC][RFC 1270], which included as part of its text: > The language reference will be extended to describe this feature as outlined in this RFC. Authors shall be advised to leave their users enough time to react before removing a deprecated item. This is not a small downside by any stretch—but adding the section to the RFC will still have all the secondary benefits noted above, and it probably at least somewhat increases the likelihood that new features do get documented. -- **Embrace the documentation, but do not include "How do we teach this?" section in new RFCs.** +- **Embrace the documentation, but do not include "How do we teach this?" section in new RFCs.** - This still gives us most of the benefits (and was in fact the original form of the proposal), and does not place a new burden on RFC authors to make sure that knowing how to *teach* something is part of any new language or standard library feature. + This still gives us most of the benefits (and was in fact the original form of the proposal), and does not place a new burden on RFC authors to make sure that knowing how to *teach* something is part of any new language or standard library feature. - On the other hand, thinking about the impact on teaching should further improve consideration of the general ergonomics of a proposed feature. If something cannot be *taught* well, it's likely the design needs further refinement. + On the other hand, thinking about the impact on teaching should further improve consideration of the general ergonomics of a proposed feature. If something cannot be *taught* well, it's likely the design needs further refinement. -- **No change; leave RFCs as canonical documentation.** +- **No change; leave RFCs as canonical documentation.** - This approach can take (at least) two forms: + This approach can take (at least) two forms: 1. We can leave things as they are, where the RFC and surrounding discussion form the primary point of documentation for newer-than-1.0 language features. As part of that, we could just link more prominently to the RFC repository and describe the process from the documentation pages. 2. We could automatically render the text of the RFCs into part of the documentation used on the site (via submodules and the existing tooling around Markdown documents used for Rust documentation). However, for all the reasons highlighted above in [**Motivation: The Current Situation**][current-situation], RFCs and their associated threads are *not* a good canonical source of information on language features. -- **Add a rule for the standard library but not for language features.** +- **Add a rule for the standard library but not for language features.** - This would basically just turn the _status quo_ into an official policy. It has all the same drawbacks as no change at all, but with the possible benefit of enabling automated checks on standard library documentation. + This would basically just turn the _status quo_ into an official policy. It has all the same drawbacks as no change at all, but with the possible benefit of enabling automated checks on standard library documentation. -- **Add a rule for language features but not for the standard library.** +- **Add a rule for language features but not for the standard library.** - The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. + The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. - On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). + On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). -- **Eliminate the reference entirely.** +- **Eliminate the reference entirely.** - Since the reference is already substantially out of date, it might make sense to stop presenting it publicly at all, at least until such a time as it has been completely reworked and updated. + Since the reference is already substantially out of date, it might make sense to stop presenting it publicly at all, at least until such a time as it has been completely reworked and updated. - The main upside to this is the reality that an outdated and inaccurate reference may be worse than no reference at all, as it may substantially mislead Rust users. + The main upside to this is the reality that an outdated and inaccurate reference may be worse than no reference at all, as it may substantially mislead Rust users. - The main downside, of course, is that this would leave very large swaths of the language basically without *any* documentation, and even more of it only documented in RFCs than is the case today. + The main downside, of course, is that this would leave very large swaths of the language basically without *any* documentation, and even more of it only documented in RFCs than is the case today. [RFC 1270]: https://github.com/rust-lang/rfcs/pull/1270 From 7dd3f1171212813d66c9d7625081ad51daf4452c Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Wed, 19 Oct 2016 11:40:46 -0400 Subject: [PATCH 17/23] Drop unresolved question about docs subteam: we have one! --- text/0000-document_all_features.md | 1 - 1 file changed, 1 deletion(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index e270a421334..81256da1207 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -271,4 +271,3 @@ At a "messaging" level, we should continue to emphasize that *documentation is j - Given that the reference is out of date, does it need to be brought up to date before beginning enforcement of this policy? - Given that the book is in the process of a rewrite for print publication, how shall we apply this requirement to RFCs merged during its development? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? -- Is a documentation subteam, _a la_ the one used by Ember, worth creating? From 88a745bf1cb15ec7121b5a62b86b7168ecec9c87 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Wed, 19 Oct 2016 11:58:55 -0400 Subject: [PATCH 18/23] Improve wording and rationale. Add some placeholders. --- text/0000-document_all_features.md | 57 +++++++++++++++++++++--------- 1 file changed, 40 insertions(+), 17 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 81256da1207..dd884728c99 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -22,7 +22,12 @@ One of the major goals of Rust's development process is *stability without stagn - [New RFC section: “How do we teach this?”](#new-rfc-section-how-do-we-teach-this) - [New requirement to document changes before stabilizing](#new-requirement-to-document-changes-before-stabilizing) - [Language features](#language-features) + - [Reference](#reference) + - [The state of the reference](#the-current-state-of-the-reference) + - [_The Rust Programming Language_][trpl] + - [_Rust By Example_][rbe] - [Standard library](#standard-library) + - [Release notes][release-notes] - [How do we teach this?](#how-do-we-teach-this) - [Drawbacks](#drawbacks) - [Alternatives](#alternatives) @@ -57,13 +62,13 @@ Although the standard library is in excellent shape regarding documentation, inc ## The Current Situation [current-situation]: #the-current-situation -Today, the canonical source of information about new language features is the RFCs which define them. +Today, the canonical source of information about new language features is the RFCs which define them. The Rust Reference is substantially out of date, and not all new features have made their way into _The Rust Programming Language_. -There are several serious problems with the _status quo_: +There are several serious problems with the _status quo_ of using RFCs as ad hoc documentation: 1. Many users of Rust may simply not know that these RFCs exist. The number of users who do not know (or especially care) about the RFC process or its history will only increase as Rust becomes more popular. -2. In many cases, especially in more complicated language features, some important elements of the decision, details of implementation, and expected behavior are fleshed out either in the associated RFC (pull-request) discussion or in the implementation issues which follow them. +2. In many cases, especially in more complicated language features, some important elements of the decision, details of implementation, and expected behavior are fleshed out either in the pull-request discussion for the RFC, or in the implementation issues which follow them. 3. The RFCs themselves, and even more so the associated pull request discussions, are often dense with programming langauge theory. This is as it should be in context, but it means that the relevant information may be inaccessible to Rust users without prior PLT background, or without the patience to wade through it. @@ -73,6 +78,8 @@ There are several serious problems with the _status quo_: In short, RFCs are a poor source of information about language features for the ordinary Rust user. Rust users should not need to be troubled with details of how the language is implemented works simply to learn how pieces of it work. Nor should they need to dig through tens (much less hundreds) of comments to determine what the final form of the feature is. +However, there is currently no other documentation at all for many newer features. This is a significant barrier to adoption of the language, and equally of adoption of new features which will improve the ergonomics of the language. + ## Precedent [precedent]: #precedent @@ -102,9 +109,9 @@ The basic decision has led to a substantial improvement in the currency of the d The basic process of developing new language features will remain largely the same as today. The required changes are two additions: -- a new section in the RFC, "How do we teach this?" modeled on Ember's updated RFC process +- [a new section in the RFC][new-rfc-section], "How do we teach this?" modeled on Ember's updated RFC process -- a new requirement that the changes themselves be properly documented before being merged to stable +- [a new requirement that the changes themselves be properly documented before being merged to stable][] ## New RFC section: "How do we teach this?" @@ -129,10 +136,12 @@ For a great example of this in practice, see the (currently open) [Ember RFC: Mo ## New requirement to document changes before stabilizing +[require-documentation-before-stabilization]: #new-requirement-to-document-changes-before-stabilizing + Prior to stabilizing a feature, the features will now be documented as follows: - Language features: - - must be documented in the reference. + - 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. @@ -143,40 +152,54 @@ Prior to stabilizing a feature, the features will now be documented as follows: ### Language features [language-features]: #language-features -We will document *all* language features in the Rust Reference, as well as making some updates to _The Rust Programming Language_ and _Rust by Example_ as necessary. +We will document *all* language features in the Rust Reference, as well as making some updates to _The Rust Programming Language_ and _Rust by Example_. + +#### Reference + +[reference]: #reference This will necessarily be a manual process, involving updates to the `reference.md` file. (It may at some point be sensible to break up the Reference file for easier maintenance; that is left aside as orthogonal to this discussion.) -Note that the feature documentation does not need to be written by the feature author. In fact, this is one of the areas where the community may be most able to support the language/compiler developers even if not themselves programming language theorists or compiler hackers. This may free up the compiler developers' time. It will also help communicate the features in a way that is accessible to ordinary Rust users. +Feature documentation does not need to be written by the feature author. In fact, this is one of the areas where the community may be most able to support the language/compiler developers even if not themselves programming language theorists or compiler hackers. This may free up the compiler developers' time. It will also help communicate the features in a way that is accessible to ordinary Rust users. New features do not need to be documented to be merged into `master`/nightly, and in many cases *should* not, since the features may change substantially before landing on stable, at which point the reference material would need to be rewritten. -Instead, the documentation process should immediately precede the move to stabilize. Once the *feature* has been deemed ready for stabilization, either the author or a community volunteer should write the *reference material* for the feature. +Instead, the documentation process should immediately precede the move to stabilize. Once the *feature* has been deemed ready for stabilization, either the author or a community volunteer should write the *reference material* for the feature, to be incorporated into the Rust Reference. -This need not be especially long, but it should be long enough for ordinary users to learn how to use the language feature *without reading the RFCs*. +The reference material need not be especially long, but it should be long enough for ordinary users to learn how to use the language feature *without reading the RFCs*. When the discussing whether to stabilize a feature in a given release, the reference material will now be a part of that decision. Once the feature *and* reference material are complete, it will be merged normally, and the pull request will simply include the reference material as well as the new feature. -Given the current state of the reference, this may need to proceed in two steps: +##### The current state of the reference. -#### The current state of the reference. [refstate]: #the-current-state-of-the-reference -Since the reference is currently fairly out of date in a number of areas, it may be worth creating a "strike team" to invest a couple months working on the reference: updating it, organizing it, and improving its presentation. (A single web page with *all* of this content is difficult to navigate at best.) This can proceed in parallel with the documentation of new features. It is probably a necessity for this proposal to be particularly effective in the long term. - -Once the reference is up to date, the nucleus responsible for that work may either disband or possibly (depending on the core team's evaluation of the necessity of it and the interest of the "strike team" members) become the basis of a new documentation subteam. +Since the reference is fairly out of date, we should create a "strike team" to update it, organize it, and improve its presentation. (A single web page with *all* of this content is difficult to navigate at best.) This can proceed in parallel with the documentation of new features. -Updating the reference could proceed stepwise: +Updating the reference may proceed stepwise: 1. Begin by adding an appendix in the reference with links to all accepted RFCs which have been implemented but are not yet referenced in the documentation. +2. As the reference material is written for each of those RFC features, remove it from that appendix. + +#### _The Rust Programming Language_ -2. As the reference material is written for each of those RFC features, it can be removed from that appendix. +[trpl]: #the-rust-programming-language + + + +#### _Rust by Example_ + +[rbe]: #rust-by-example ### Standard library [std]: #standard-library In the case of the standard library, this could conceivably be managed by setting the `#[forbid(missing_docs)]` attribute on the library roots. In lieu of that, manual code review and general discipline should continue to serve. However, if automated tools *can* be employed here, they should. +### Release Notes + +[release-notes]: #release-notes + # How do we teach this? From 2738cb7c30c848045b4c14afa7fa7fd60219e612 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Wed, 19 Oct 2016 12:29:39 -0400 Subject: [PATCH 19/23] Fix a couple link refs. --- text/0000-document_all_features.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index dd884728c99..d0c08b9d57c 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -30,8 +30,8 @@ One of the major goals of Rust's development process is *stability without stagn - [Release notes][release-notes] - [How do we teach this?](#how-do-we-teach-this) - [Drawbacks](#drawbacks) -- [Alternatives](#alternatives) -- [Unresolved questions](#unresolved-questions) +- [Alternatives][alternatives] +- [Unresolved questions][unresolved-questions] # Motivation @@ -111,7 +111,7 @@ The basic process of developing new language features will remain largely the sa - [a new section in the RFC][new-rfc-section], "How do we teach this?" modeled on Ember's updated RFC process -- [a new requirement that the changes themselves be properly documented before being merged to stable][] +- [a new requirement that the changes themselves be properly documented before being merged to stable][require-documentation-before-stabilization] ## New RFC section: "How do we teach this?" From 7ae5c6b809a0dfee482429ef136f87dc242a2d96 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Wed, 19 Oct 2016 13:38:59 -0400 Subject: [PATCH 20/23] Address a number of concerns. - Drop unneeded stubs. - Fix RFC should/must/may language in a number of places. - Drop inline Ember references in How Do We Teach This. - Clarify the book process. - Clarify the expected reference update process --- text/0000-document_all_features.md | 71 +++++++++++++----------------- 1 file changed, 31 insertions(+), 40 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index d0c08b9d57c..446fba1b644 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -25,9 +25,7 @@ One of the major goals of Rust's development process is *stability without stagn - [Reference](#reference) - [The state of the reference](#the-current-state-of-the-reference) - [_The Rust Programming Language_][trpl] - - [_Rust By Example_][rbe] - - [Standard library](#standard-library) - - [Release notes][release-notes] + - [Standard library][standard-library] - [How do we teach this?](#how-do-we-teach-this) - [Drawbacks](#drawbacks) - [Alternatives][alternatives] @@ -111,24 +109,22 @@ The basic process of developing new language features will remain largely the sa - [a new section in the RFC][new-rfc-section], "How do we teach this?" modeled on Ember's updated RFC process -- [a new requirement that the changes themselves be properly documented before being merged to stable][require-documentation-before-stabilization] +- [a new requirement][require-documentation-before-stabilization] that the changes themselves be properly documented before being merged to stable ## New RFC section: "How do we teach this?" [new-rfc-section]: #new-rfc-section-how-do-we-teach-this -Following the example of Ember.js, we will add a new section to the RFC, just after **Detailed design**, titled **How do we teach this?** The section should to 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_. +Following the example of Ember.js, we must add a new section to the RFC, just after **Detailed design**, titled **How do we teach this?** 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_. -Here is the Ember RFC section, with suggested substitutions: +Here is the Ember RFC section, with appropriate substitutions and modifications: > # How We Teach This -> What names and terminology work best for these concepts and why? How is this idea best presented? As a continuation of existing ~~Ember~~ **Rust** patterns, or as a wholly new one? +> 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 mean ~~Ember guides~~ **_The Rust Programing Language_, _Rust by Example_, or the Rust Reference** must be re-organized or altered? Does it change how ~~Ember~~ **Rust** is taught to new users at any level? +> 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 ~~Ember~~ **Rust** users? - -We may also find it valuable to add other, more Rust-specific (or programming language- rather than framework-specific) verbiage there. +> How should this feature be introduced and taught to existing Rust users? For a great example of this in practice, see the (currently open) [Ember RFC: Module Unification], which includes several sections discussing conventions, tooling, concepts, and impacts on testing. @@ -149,10 +145,12 @@ Prior to stabilizing a feature, the features will now be documented as follows: - 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. + ### Language features [language-features]: #language-features -We will document *all* language features in the Rust Reference, as well as making some updates to _The Rust Programming Language_ and _Rust by Example_. +We will document *all* language features in the Rust Reference, as well as updating _The Rust Programming Language_ and _Rust by Example_ as appropriate. (Not all features or changes will require updates to the books.) #### Reference @@ -162,45 +160,40 @@ This will necessarily be a manual process, involving updates to the `reference.m Feature documentation does not need to be written by the feature author. In fact, this is one of the areas where the community may be most able to support the language/compiler developers even if not themselves programming language theorists or compiler hackers. This may free up the compiler developers' time. It will also help communicate the features in a way that is accessible to ordinary Rust users. -New features do not need to be documented to be merged into `master`/nightly, and in many cases *should* not, since the features may change substantially before landing on stable, at which point the reference material would need to be rewritten. +New features do not need to be documented to be merged into `master`/nightly Instead, the documentation process should immediately precede the move to stabilize. Once the *feature* has been deemed ready for stabilization, either the author or a community volunteer should write the *reference material* for the feature, to be incorporated into the Rust Reference. The reference material need not be especially long, but it should be long enough for ordinary users to learn how to use the language feature *without reading the RFCs*. -When the discussing whether to stabilize a feature in a given release, the reference material will now be a part of that decision. Once the feature *and* reference material are complete, it will be merged normally, and the pull request will simply include the reference material as well as the new feature. +Discussion of stabilizing a feature in a given release will now include the status of the reference material. -##### The current state of the reference. +##### The current state of the reference [refstate]: #the-current-state-of-the-reference -Since the reference is fairly out of date, we should create a "strike team" to update it, organize it, and improve its presentation. (A single web page with *all* of this content is difficult to navigate at best.) This can proceed in parallel with the documentation of new features. +Since the reference is fairly out of date, we should create a "strike team" to update it. This can proceed in parallel with the documentation of new features. -Updating the reference may proceed stepwise: +Updating the reference should proceed stepwise: 1. Begin by adding an appendix in the reference with links to all accepted RFCs which have been implemented but are not yet referenced in the documentation. 2. As the reference material is written for each of those RFC features, remove it from that appendix. +The current presentation of the reference is also in need of improvement: a single web page with *all* of this content is difficult to navigate, or to update. Therefore, the strike team may also take this opportunity to reorganize the reference and update its presentation. + #### _The Rust Programming Language_ [trpl]: #the-rust-programming-language +Most new language features should be added to _The Rust Programming Language_. However, since the book is planned to go to print, the main text of the book is expected to be fixed between major revisions. As such, new features should be documented in an online appendix to the book, which may be titled e.g. "Newest Features." - -#### _Rust by Example_ - -[rbe]: #rust-by-example +The published version of the book should note that changes and languages features made available after the book went to print will be documented in that online appendix. ### Standard library -[std]: #standard-library +[standard-library]: #standard-library In the case of the standard library, this could conceivably be managed by setting the `#[forbid(missing_docs)]` attribute on the library roots. In lieu of that, manual code review and general discipline should continue to serve. However, if automated tools *can* be employed here, they should. -### Release Notes - -[release-notes]: #release-notes - - # How do we teach this? Since this RFC promotes including this section, it includes it itself. (RFCs, unlike Rust `struct` or `enum` types, may be freely self-referential. No boxing required.) @@ -244,7 +237,7 @@ At a "messaging" level, we should continue to emphasize that *documentation is j - **Just add the "How do we teach this?" section.** - Of all the alternatives, this is the easiest (and probably the best). It does not substantially change the state with regard to the documentation, and even having the section in the RFC does not mean that it will end up added to the docs, as evidence by the [`#[deprecated]` RFC][RFC 1270], which included as part of its text: + Of all the alternatives, this is the easiest (and probably the best). It does not substantially change the state with regard to the documentation, and even having the section in the RFC does not mean that it will end up added to the docs, as evidence by the [`#[deprecated]` RFC][RFC 1270], which included as part of its text: > The language reference will be extended to describe this feature as outlined in this RFC. Authors shall be advised to leave their users enough time to react before removing a deprecated item. @@ -252,13 +245,14 @@ At a "messaging" level, we should continue to emphasize that *documentation is j - **Embrace the documentation, but do not include "How do we teach this?" section in new RFCs.** - This still gives us most of the benefits (and was in fact the original form of the proposal), and does not place a new burden on RFC authors to make sure that knowing how to *teach* something is part of any new language or standard library feature. + This still gives us most of the benefits (and was in fact the original form of the proposal), and does not place a new burden on RFC authors to make sure that knowing how to *teach* something is part of any new language or standard library feature. - On the other hand, thinking about the impact on teaching should further improve consideration of the general ergonomics of a proposed feature. If something cannot be *taught* well, it's likely the design needs further refinement. + On the other hand, thinking about the impact on teaching should further improve consideration of the general ergonomics of a proposed feature. If something cannot be *taught* well, it's likely the design needs further refinement. - **No change; leave RFCs as canonical documentation.** - This approach can take (at least) two forms: + This approach can take (at least) two forms: + 1. We can leave things as they are, where the RFC and surrounding discussion form the primary point of documentation for newer-than-1.0 language features. As part of that, we could just link more prominently to the RFC repository and describe the process from the documentation pages. 2. We could automatically render the text of the RFCs into part of the documentation used on the site (via submodules and the existing tooling around Markdown documents used for Rust documentation). @@ -267,21 +261,21 @@ At a "messaging" level, we should continue to emphasize that *documentation is j - **Add a rule for the standard library but not for language features.** - This would basically just turn the _status quo_ into an official policy. It has all the same drawbacks as no change at all, but with the possible benefit of enabling automated checks on standard library documentation. + This would basically just turn the _status quo_ into an official policy. It has all the same drawbacks as no change at all, but with the possible benefit of enabling automated checks on standard library documentation. - **Add a rule for language features but not for the standard library.** - The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. + The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. - On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). + On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). - **Eliminate the reference entirely.** - Since the reference is already substantially out of date, it might make sense to stop presenting it publicly at all, at least until such a time as it has been completely reworked and updated. + Since the reference is already substantially out of date, it might make sense to stop presenting it publicly at all, at least until such a time as it has been completely reworked and updated. - The main upside to this is the reality that an outdated and inaccurate reference may be worse than no reference at all, as it may substantially mislead Rust users. + The main upside to this is the reality that an outdated and inaccurate reference may be worse than no reference at all, as it may mislead espiecally new Rust users. - The main downside, of course, is that this would leave very large swaths of the language basically without *any* documentation, and even more of it only documented in RFCs than is the case today. + The main downside, of course, is that this would leave very large swaths of the language basically without *any* documentation, and even more of it only documented in RFCs than is the case today. [RFC 1270]: https://github.com/rust-lang/rfcs/pull/1270 @@ -290,7 +284,4 @@ At a "messaging" level, we should continue to emphasize that *documentation is j [unresolved]: #unresolved-questions - How do we clearly distinguish between features on nightly, beta, and stable Rust—in the reference especially, but also in the book? -- How will the requirement for documentation in the reference be enforced? -- Given that the reference is out of date, does it need to be brought up to date before beginning enforcement of this policy? -- Given that the book is in the process of a rewrite for print publication, how shall we apply this requirement to RFCs merged during its development? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? From 2d33ba1bdf03a9aedb87c24a7c0e792ffd87e00e Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Wed, 19 Oct 2016 13:45:12 -0400 Subject: [PATCH 21/23] Drop internal links. (They're finicky, alas.) --- text/0000-document_all_features.md | 74 +++++++++++++----------------- 1 file changed, 32 insertions(+), 42 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 446fba1b644..abb4ef7f9b7 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -5,35 +5,32 @@ # Summary -[summary]: #summary One of the major goals of Rust's development process is *stability without stagnation*. That means we add features regularly. However, it can be difficult to *use* those features if they are not publicly documented anywhere. Therefore, this RFC proposes requiring that all new language features and public standard library items must be documented before landing on the stable release branch (item documentation for the standard library; in the language reference for language features). ## Outline -[outline]: #outline - -- [Summary](#summary) - - [Outline](#outline) -- [Motivation](#motivation) - - [The Current Situation](#the-current-situation) - - [Precedent](#precedent) -- [Detailed design](#detailed-design) - - [New RFC section: “How do we teach this?”](#new-rfc-section-how-do-we-teach-this) - - [New requirement to document changes before stabilizing](#new-requirement-to-document-changes-before-stabilizing) - - [Language features](#language-features) - - [Reference](#reference) - - [The state of the reference](#the-current-state-of-the-reference) - - [_The Rust Programming Language_][trpl] - - [Standard library][standard-library] -- [How do we teach this?](#how-do-we-teach-this) -- [Drawbacks](#drawbacks) -- [Alternatives][alternatives] -- [Unresolved questions][unresolved-questions] + +- Summary + - Outline +- Motivation + - The Current Situation + - Precedent +- Detailed design + - New RFC section: “How do we teach this?” + - New requirement to document changes before stabilizing + - Language features + - Reference + - The state of the reference + - _The Rust Programming Language_ + - Standard library +- How do we teach this? +- Drawbacks +- Alternatives +- Unresolved questions # Motivation -[motivation]: #motivation 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. @@ -58,7 +55,6 @@ Changing this to require all language features to be documented before stabiliza Although the standard library is in excellent shape regarding documentation, including it in this policy will help guarantee that it remains so going forward. ## The Current Situation -[current-situation]: #the-current-situation Today, the canonical source of information about new language features is the RFCs which define them. The Rust Reference is substantially out of date, and not all new features have made their way into _The Rust Programming Language_. @@ -79,7 +75,6 @@ In short, RFCs are a poor source of information about language features for the However, there is currently no other documentation at all for many newer features. This is a significant barrier to adoption of the language, and equally of adoption of new features which will improve the ergonomics of the language. ## Precedent -[precedent]: #precedent This exact idea has been adopted by the Ember community after their somewhat bumpy transitions at the end of their 1.x cycle and leading into their 2.x transition. As one commenter there [put it][@davidgoli]: @@ -103,17 +98,15 @@ The basic decision has led to a substantial improvement in the currency of the d # Detailed design -[design]: #detailed-design The basic process of developing new language features will remain largely the same as today. The required changes are two additions: -- [a new section in the RFC][new-rfc-section], "How do we teach this?" modeled on Ember's updated RFC process +- a new section in the RFC, "How do we teach this?" modeled on Ember's updated RFC process -- [a new requirement][require-documentation-before-stabilization] that the changes themselves be properly documented before being merged to stable +- a new requirement that the changes themselves be properly documented before being merged to stable ## New RFC section: "How do we teach this?" -[new-rfc-section]: #new-rfc-section-how-do-we-teach-this Following the example of Ember.js, we must add a new section to the RFC, just after **Detailed design**, titled **How do we teach this?** 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_. @@ -148,7 +141,6 @@ Prior to stabilizing a feature, the features will now be documented as follows: 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. ### Language features -[language-features]: #language-features We will document *all* language features in the Rust Reference, as well as updating _The Rust Programming Language_ and _Rust by Example_ as appropriate. (Not all features or changes will require updates to the books.) @@ -190,7 +182,6 @@ Most new language features should be added to _The Rust Programming Language_. H The published version of the book should note that changes and languages features made available after the book went to print will be documented in that online appendix. ### Standard library -[standard-library]: #standard-library In the case of the standard library, this could conceivably be managed by setting the `#[forbid(missing_docs)]` attribute on the library roots. In lieu of that, manual code review and general discipline should continue to serve. However, if automated tools *can* be employed here, they should. @@ -217,13 +208,12 @@ At a "messaging" level, we should continue to emphasize that *documentation is j # Drawbacks -[drawbacks]: #drawbacks 1. The largest drawback at present is that the language reference is *already* quite out of date. It may take substantial work to get it up to date so that new changes can be landed appropriately. (Arguably, however, this should be done regardless, since the language reference is an important part of the language ecosystem.) 2. Another potential issue is that some sections of the reference are particularly thorny and must be handled with considerable care (e.g. lifetimes). Although in general it would not be necessary for the author of the new language feature to write all the documentation, considerable extra care and oversight would need to be in place for these sections. -3. This may delay landing features on stable. However, all the points raised in [**Precedent**][precedent] on this apply, especially: +3. This may delay landing features on stable. However, all the points raised in **Precedent** on this apply, especially: > We can't get the great new toys unless everybody can enjoy the toys. ([@eccegordo]) @@ -233,7 +223,6 @@ At a "messaging" level, we should continue to emphasize that *documentation is j # Alternatives -[alternatives]: #alternatives - **Just add the "How do we teach this?" section.** @@ -245,19 +234,19 @@ At a "messaging" level, we should continue to emphasize that *documentation is j - **Embrace the documentation, but do not include "How do we teach this?" section in new RFCs.** - This still gives us most of the benefits (and was in fact the original form of the proposal), and does not place a new burden on RFC authors to make sure that knowing how to *teach* something is part of any new language or standard library feature. + This still gives us most of the benefits (and was in fact the original form of the proposal), and does not place a new burden on RFC authors to make sure that knowing how to *teach* something is part of any new language or standard library feature. - On the other hand, thinking about the impact on teaching should further improve consideration of the general ergonomics of a proposed feature. If something cannot be *taught* well, it's likely the design needs further refinement. + On the other hand, thinking about the impact on teaching should further improve consideration of the general ergonomics of a proposed feature. If something cannot be *taught* well, it's likely the design needs further refinement. - **No change; leave RFCs as canonical documentation.** - This approach can take (at least) two forms: + This approach can take (at least) two forms: 1. We can leave things as they are, where the RFC and surrounding discussion form the primary point of documentation for newer-than-1.0 language features. As part of that, we could just link more prominently to the RFC repository and describe the process from the documentation pages. 2. We could automatically render the text of the RFCs into part of the documentation used on the site (via submodules and the existing tooling around Markdown documents used for Rust documentation). - However, for all the reasons highlighted above in [**Motivation: The Current Situation**][current-situation], RFCs and their associated threads are *not* a good canonical source of information on language features. + However, for all the reasons highlighted above in **Motivation: The Current Situation**, RFCs and their associated threads are *not* a good canonical source of information on language features. - **Add a rule for the standard library but not for language features.** @@ -265,23 +254,24 @@ At a "messaging" level, we should continue to emphasize that *documentation is j - **Add a rule for language features but not for the standard library.** - The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. + The standard library is in much better shape, in no small part because of the ease of writing inline documentation for new modules. Adding a formal rule may not be necessary if good habits are already in place. - On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). + On the other hand, having a formal policy would not seem to *hurt* anything here; it would simply formalize what is already happening (and perhaps, via linting attributes, make it easy to spot when it has failed). - **Eliminate the reference entirely.** - Since the reference is already substantially out of date, it might make sense to stop presenting it publicly at all, at least until such a time as it has been completely reworked and updated. + Since the reference is already substantially out of date, it might make sense to stop presenting it publicly at all, at least until such a time as it has been completely reworked and updated. - The main upside to this is the reality that an outdated and inaccurate reference may be worse than no reference at all, as it may mislead espiecally new Rust users. + The main upside to this is the reality that an outdated and inaccurate reference may be worse than no reference at all, as it may mislead espiecally new Rust users. - The main downside, of course, is that this would leave very large swaths of the language basically without *any* documentation, and even more of it only documented in RFCs than is the case today. + The main downside, of course, is that this would leave very large swaths of the language basically without *any* documentation, and even more of it only documented in RFCs than is the case today. [RFC 1270]: https://github.com/rust-lang/rfcs/pull/1270 # Unresolved questions -[unresolved]: #unresolved-questions - How do we clearly distinguish between features on nightly, beta, and stable Rust—in the reference especially, but also in the book? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? + +[detailed-design]: From 3ad263e3cba5d61613ac91d83d49e101ce251271 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Wed, 19 Oct 2016 14:13:29 -0400 Subject: [PATCH 22/23] Drop extraneous link item. --- text/0000-document_all_features.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index abb4ef7f9b7..916cc2d6be9 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -273,5 +273,3 @@ At a "messaging" level, we should continue to emphasize that *documentation is j - How do we clearly distinguish between features on nightly, beta, and stable Rust—in the reference especially, but also in the book? - For the standard library, once it migrates to a crates structure, should it simply include the `#[forbid(missing_docs)]` attribute on all crates to set this as a build error? - -[detailed-design]: From 3d882f95d5d1b418ecb44c1dab6223a8fdf7f2c6 Mon Sep 17 00:00:00 2001 From: Chris Krycho Date: Fri, 21 Oct 2016 12:11:17 -0400 Subject: [PATCH 23/23] Fix a typo; clarify some language. --- text/0000-document_all_features.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0000-document_all_features.md b/text/0000-document_all_features.md index 916cc2d6be9..4f9c7737eae 100644 --- a/text/0000-document_all_features.md +++ b/text/0000-document_all_features.md @@ -42,7 +42,7 @@ Importantly, though, this warning only appears on the [main site][home-to-refere [home-to-reference]: https://www.rust-lang.org/documentation.html -For example, the change in Rust 1.9 to allow users to use the `#[deprecated]` attribute for their own libraries is, at the time of writing this RFC, *nowhere* reflected in official documentation. (Many other examples could be supplied; this one is chosen for its relative simplicity and recency.) The Book's [discussion of attributes][book-attributes] links to the [reference list of attributes][ref-attributes], but as of the time of writing the reference [still specifies][ref-compiler-attributes] that `deprecated` is a compiler-only feature. The two places where users might become aware of the change are [the Rust 1.9 release blog post][1.9-blog] and the [RFC itself][RFC-1270]. Neither (yet) ranks highly in search; users are likely to be misled. +For example, the change in Rust 1.9 to allow users to use the `#[deprecated]` attribute for their own libraries was, at the time of writing this RFC, *nowhere* reflected in official documentation. (Many other examples could be supplied; this one was chosen for its relative simplicity and recency.) The Book's [discussion of attributes][book-attributes] linked to the [reference list of attributes][ref-attributes], but as of the time of writing the reference [still specifies][ref-compiler-attributes] that `deprecated` was a compiler-only feature. The two places where users might have become aware of the change are [the Rust 1.9 release blog post][1.9-blog] and the [RFC itself][RFC-1270]. Neither (yet) ranked highly in search; users were likely to be misled. [book-attributes]: https://doc.rust-lang.org/book/attributes.html [ref-attributes]: https://doc.rust-lang.org/reference.html#attributes @@ -64,7 +64,7 @@ There are several serious problems with the _status quo_ of using RFCs as ad hoc 2. In many cases, especially in more complicated language features, some important elements of the decision, details of implementation, and expected behavior are fleshed out either in the pull-request discussion for the RFC, or in the implementation issues which follow them. -3. The RFCs themselves, and even more so the associated pull request discussions, are often dense with programming langauge theory. This is as it should be in context, but it means that the relevant information may be inaccessible to Rust users without prior PLT background, or without the patience to wade through it. +3. The RFCs themselves, and even more so the associated pull request discussions, are often dense with programming language theory. This is as it should be in context, but it means that the relevant information may be inaccessible to Rust users without prior PLT background, or without the patience to wade through it. 4. Similarly, information about the final decisions on language features is often buried deep at the end of long and winding threads (especially for a complicated feature like `impl` specialization).