RFC: Require documentation for all new features.

[chriskrycho]

Rendered

Note: I used #[deprecated] as an example in this... and I submitted a PR to update it right after I submitted this PR.

[anp]

This might be out of scope for this particular RFC, but since you mentioned Ember... Just thought it was worth mentioning that a part of the feature documentation process for them appears to be a "How we teach this" section of RFCs:

https://github.com/dgeb/rfcs/blob/module-unification/text/0000-module-unification.md#how-we-teach-this

Seems to me like a great way to have documentation (and thus user onboarding) in mind as part of the RFC process.

[chriskrycho]

@dikaiosune: excellent link (I was trying to find it earlier, and @steveklabnik mentioned it elsewhere as well), and I think that actually should be included, probably as part of the Detailed Process section. I'll add it to the writeup sometime tomorrow.

[anp]

I think that'd be great -- especially because (IMO) part of having good documentation is making sure that features can be sanely documented and taught. I see it come up in RFC discussions, but it'd be nice to formalize as part of the process before an implementation happens (again, IMO).

[acorncom]

I'm on the Ember Documentation / Learning team and would highly recommend this. Once the documentation stopped falling further and further behind, there was actually some motivation to improve things. 😄 We're still catching up on places, but at this point, about a year later, things are finally in reasonable shape.

We'd be happy to discuss things further if it'd be useful ...

[jugglerchris]

As a user not (so far) involved in the core, this gets an enthusiastic vote from me. As an example the for<'a> construct is neither discoverable in the reference, nor Googlable if you come across an example of it.

I think an appendix in the reference with links to accepted RFCs not yet incorporated into the documentation would be a move in the right direction.

[chriskrycho]

I've updated the RFC slightly to account for those pieces of feedback:

• I added a call to add the Ember-inspired "How do we document this?" section.
• I added a "How do we document this?" section to this RFC. That includes some thoughts on how to make sure this is a community effort, not just piling more work on @steveklabnik.
• I added some thoughts on how a community subteam might be useful.
• I added an addendum discussing the possible necessity of a "strike team" to get the current reference up to date as well.

@acorncom, I'd be particularly interested to hear what the Ember team has found most effective in helping get the community to step in and work on the docs—it's one of those things that people hear a lot ("Contribute to the docs!"), but I imagine it's hard to actually get people engaged that way?

[chriskrycho]

@jugglerchris, I also just went back and included your suggestion of an appendix for implemented-but-not-yet-documented RFCs, as I quite like that as a useful intermediate step.

[nagisa]

I guess changing the template 0000-template.md or whatever that’s called should be part of this PR.

[chriskrycho]

I plan to submit that in an "implementation" PR if this is accepted (and discuss it below).

[kylone]

It may be worthwhile to create new RFCs to update documentation for existing language features that aren't documented well in the reference, so that the process can be formalized. (Assuming hat this RFC is accepted.)

[nagisa]

It may be worthwhile to create new RFCs… for existing language features

There’s nothing worthwhile to discuss about existing features other than removing (EDIT: or changing) them on the RFC scale. That should be done in forums, IRC and other less involving channels.

[chriskrycho]

@nagisa, that's true in the "RFC" sense but not the general sense: there's plenty to discuss in terms of documenting a lot of existing language features (they're certainly not all documented now; the lack is part of what prompted this RFC). @kylone, we'd want to create issues to track those rather than RFCs. See When you need to follow this process in the RFCs README.

[withoutboats]

I worked abortively on an RFC along the same lines a few weeks ago, but this is much more comprehensive. Well done! 🎈🎈

I'm not sure what should be done about the reference, though. The main way language features are taught is through the book, not the reference - but the documentation in the book is more laborious than the documentation in the reference, and it might not be reasonable to gate stabilization on giving the feature a proper "book" treatment. I suppose that requiring a "reference" treatment of every feature will finally give the reference a real purpose and some attention (I personally use the reference almost exclusively for ransacking reserved words to paint a bikeshed with).

[chriskrycho]

@withoutboats: thanks! I think you're right that it should not require putting it in the book, but should require documentation in general. That's part of what I was thinking in the "How do we teach this?" section discussion: we can specify when writing new RFCs where it makes the most sense to put the new information—and that can be either or both of the reference and The Rust Programming Language, and optionally also Rust by Example (which I found enormously helpful as an introduction to the language for myself).

[azerupi]

it might not be reasonable to gate stabilization on giving the feature a proper "book" treatment.

The book is the most used and most comprehensive source of information about Rust. If I need to find an explanation about something, I expect to find it in the book. Depending on the feature, it could need just a paragraph or it could need a whole chapter. Considering that a new feature will take at the very least 6 weeks to go stable and knowing that bigger features will also have longer testing phases, I don't think it's unreasonable to ask for documentation in the book.

If we don't require the book to be up to date before / while stabilizing, this means the work is mostly relegated to Steve Klabnik. The time he has to spend keeping up with new language features is time he can't spend improving the other parts of the book.

[chriskrycho]

@azerupi, FWIW, my take is that we should document a given feature wherever is appropriate for a given feature. For example, I don't think we need a list of every #[attribute] and its applicability in The Rust Programming Language, but we do need a description of attributes and how they work in general there, and we do need that exhaustive list, presumably in the reference.

I can further clarify the RFC if it's missing that emphasis; I thought it was clear that part of the RFC process, with this revision, would entail discussing where and how to document any given feature. That's what I assume would be included in "How do we teach this?" and would be discussed in the RFC along the way.

The last thing I want to do is land yet more work on @steveklabnik's plate; he has plenty as it is. But requiring that everything land in the book, or not, seems to me to be orthogonal to whether Steve is the one writing all of it. (Other people can update the book; Steve can update the reference.) Do you see a spot in the RFC where I should clarify the wording to make that clearer?

[azerupi]

@chriskrycho No it's good :)

My response was more directed at @withoutboats because his proposition seemed to imply that no feature should be blocked for not being documented in the book because it could take some time to write about it.

It does indeed not make sense to document all the features in the book, but a lot of them can and should be. When saying this I am more thinking about features like specialization. I would find it normal to require a section in the book about that. Blocking stabilization while documentation is lacking will make sure that the documentation gets the treatment it deserves. Even features like #[deprecated] are good to mention in the book, even if it's only in one sentence with a link to somewhere else. Because people going through the book will at least know that it exists.

[acorncom]

@chriskrycho Re: your question:

I'd be particularly interested to hear what the Ember team has found most effective in helping get the community to step in and work on the docs—it's one of those things that people hear a lot ("Contribute to the docs!"), but I imagine it's hard to actually get people engaged that way?

As far as getting folks to contribute, we've got contributions on three levels roughly:

• minor tweaks to fix tiny bugs in the guides (spelling mistakes, logic issues, etc)
• decent chunks of work (editing a section of the site, hitting one topic issue that spreads across the guides)
• major pieces of work that involve coordinated work across a period of time

For the minor tweaks, adding our "Edit this page" icon meant that the small bugs are something we don't spend much time thinking about (people tell us if they find something unclear). It has turned each user of the docs into a beta tester who might send in feedback. We're going to need to add that to the API docs as well (which are still a bit outdated) once we have made some infrastructure changes.

For decent chunks of work, having labeled issues in the guides repo with the work laid out clearly seems to have led to people contributing the most. If people ask how they can help, we point them there. With these types of issues, we tend toward a facilitating role ("let us know if you have questions as you dig in") Although I have to be a bit careful with it (I've probably said it to you too much @chriskrycho 😉 ) the "hey, send in a PR 😄 " comment has also led to contributions in this vein. Having it stated clearly (and regularly in different ways) that keeping the documentation up-to-date is a major undertaking and we'd love to get help has led to a number of different major contributions that we didn't have the bandwidth for.

For the really large pieces of work that require on-going discussion (and background on how we're wanting the guides to work), we tend to reserve those for the learning team to work on. Not all our issues are labeled "help wanted" and we keep some larger items on a private Trello board where we track and discuss things, as they would be very hard for outside contributors to help with. Having meetings weekly (or as close as possible to that) has also helped us work together as a team (as we regularly discuss what our top priorities should be and what things need to be put on hold due to time constraints).

For Rust, what I'm hearing as part of this discussion is that Steve Klabnick is the main guy for documentation. If that's the case (it's where Ember was a year+ ago), I would suggest putting out a "call for help" to see if you can find a few more folks who are willing to join the docs team. It was only once there were multiple people working on the Ember docs (in addition to the core team's commitment to not add new code without documentation) that they turned around. Without a team approach, keeping documentation up-to-date can turn into a major chore ...

Does that help? Would love to chat about it here (or offline) further if it's useful ...

[steveklabnik]

this link is broken

[chriskrycho]

Fixed! Thanks. 👍

[steveklabnik]

Hi @chriskrycho ! Thanks for this RFC. And thanks to everyone who's commented so far.

I have... complicated feels about this. I do love, love, love the "how will we teach this" part. Regardless of the rest of this RFC, I would like to see that proposed.

I should also mention that we have been working on spinning up a docs team. We have weekly meetings, and we're sort of in the final stages of making it official. If you'd like to help, please come by! The next meeting will be on Wednesday 8th of June 2016 at 20:00 GMT on #rust-docs channel in irc.mozilla.org.

In general, I am pro "it's not a real feature until it's documented" as a concept, but am extremely worried about becoming even more overburdened than I am already. This RFC does have some suggestions, and maybe with it as a forcing function, more will be interested in helping out with docs. I dunno.

I am torn about the reference. For some fun/sad history here: rust-lang/rust#20137

At various times, I have suggested that maybe the book should get more reference-y, and subsume it entirely. That said, I think this is probably the wrong choice; the book shouldn't explain every last detail of everything. But it would be nice if the reference saw more love; as you've said, it's accurate, but not complete. Most of my time writing docs these days is being spent on the second edition of the book. It was going a bit slow for a while, but has been going faster lately; it's going to be great, but it also takes time. The weird thing about it is that the beginning is the hardest part; I took way longer on the first chapters than I expect to on the later ones, because the later ones mean you already know most of Rust! So it's a bit easier.

There's also been a discussion over the years of "how much like a spec should the reference be?" Which is an interesting and tough question. In general, I see the layout of the docs like this:

• Book: "How do I learn Rust?"
• API docs: "I know Rust, but I want to know how to use the standard library"
• Reference: "I know Rust, but I want to learn about a particular thing in great detail."

In other words, I see the reference as being just as big of a job as the book, but with a different focus/voice. In some ways, it's a bigger job, as it should have more details in it! At the same time, it doesn't need tons of examples, etc. So it might be literally smaller, text-wise.

Anyway, I think that's what's been in my brain over the weekend. In general, regardless of this RFC, if anyone wants to get more involved with docs, we'd love to have your help. Please drop by IRC and ping me.

[brson]

Oh, I have one other technical issue with updating the changelog.

As a requirement for marking a feature as stable one must update the changelog (RELEASES.md). But the format of RELEASES.md is such that it contains links to some PR, usually the PR doing the stabilization. There's a bit of a chicken and egg problem there, though one could imagine the author submits a PR then adds its link by amending the commits.

[chriskrycho]

(GAH. GitHub just crashed my browser; that was fun.)

Thanks, @brson!

A couple quick responses

I don't think this sentence should mention the core team. More like "less experienced community members". It's not just the core team that writes docs today.

Thought I got all those! Will patch.

Where does this go? It doesn't seem to be specified. Should authors stabilizing features literally be posting patches to blog.rust-lang.org?

Great question! You actually suggested that bit, so do you have thoughts? I liked the idea but didn't know where it should go.

The language here still reads as an unenforceable wishlist to me: "should create a strike team". It sounds to me like we aren't going to do what's in this section. Certainly this RFC doesn't itself create a "strike team". In general, I'm skeptical that anybody is going to step up and take ownership of the reference just because the RFC says somebody "should".

Fair. I guess my question is: what would it take to prioritize this? (Note as well that I used should instead of must there advisedly.) I'm happy to bring it up on the 2017 RFC thread, for example—as I think it actually does make a big difference in approachability and learnability for this stuff actually to be documented.

Also, as I stated way up-thread (though, this being an RFC, it's not a surprise to me if someone hasn't read every comment in the thread 😂), I'm happy to contribute a bit of time every week to help with that. Even just 15–30 minutes every week will add up. The main thing I need is someone to figure out what needs changing.

As a requirement for marking a feature as stable one must update the changelog (RELEASES.md). But the format of RELEASES.md is such that it contains links to some PR, usually the PR doing the stabilization. There's a bit of a chicken and egg problem there, though one could imagine the author submits a PR then adds its link by amending the commits.

Ah, procedural info I didn't realize. Happy to amend this however makes the most sense process-wise.

[brson]

Great question! You actually suggested that bit, so do you have thoughts? I liked the idea but didn't know where it should go.

I'm inclined to drop the requirement for the long-form description, and just go for the changelog line, simply because we don't have a place to collect this stuff, and because if we actually had such paragraphs it would imply changes to the structure of our release announcements we haven't thought through. But it would be amazing if every new feature had a paragraph explaining and demonstrating it... Maybe @steveklabnik has opinions. I guess we could for now just say to write it up in the PR.

what would it take to prioritize this?

Probably just some individual with the motivation to keep pressing on it.

I'm happy to contribute a bit of time every week to help with that.

Like you...

Ah, procedural info I didn't realize. Happy to amend this however makes the most sense process-wise.

Sigh. I don't know. I feel like let's just whatever, ya' know. It's been long enough.

[brson]

Waiting on FCP approval from @erickt and @pcwalton (click the checkboxes)

[erickt]

@brson checked!

[steveklabnik]

But it would be amazing if every new feature had a paragraph explaining and demonstrating it... Maybe @steveklabnik has opinions.

In projects I've worked on in the past, after a release, we'd create a space in the changelog for the next release, and people would have to modify it with their PRs. This is a recipe for merge conflicts though...

Frankly, the best option, imho, is to be a bit more stringent about commit messages, and put that info in there. Then, when writing the release notes, I can look at the PR directly.

Well, that's my best idea this early in the morning anyway 😉

[chriskrycho]

@brson:

...it would be amazing if every new feature had a paragraph explaining and demonstrating it...

You know, I just realized... if we actually have documentation in the reference, we have that! 😂 The changelog can just link to the API docs for the stdlib or to the reference for language features.

[carols10cents]

Waiting on FCP approval from @erickt and @pcwalton (click the checkboxes)

It looks like they checked the check boxes, does this go to FCP now? Does someone have to manually add the label? (idk how this works really, poking in case this got missed, i'm so excited for this RFC!)

[anp]

@carols10cents rfcbot is having a bad day -- I'm trying to find time to diagnose and fix

EDIT: Looks like the 2 concerns listed weren't ever resolved. They're currently checked independently from individual team members' reviews.

[brson]

This RFC is in FCP.

[carols10cents]

Hiiii I thought FCP was supposed to be 1 week, this looks like it's been in FCP for 3? Am I misunderstanding something, or did it get lost in election/holiday shuffle?

[aturon]

@carols10cents Oy, good catch! It looks like the FCP label was applied manually, and we've come to rely on the bot adding a comment when FCP is over.

In any case, given that we've long since reached consensus here, I'm going to go ahead and merge. @chriskrycho, thanks again for sticking with it!

[chriskrycho]

Huzzah! 🎉

[llogiq]

Yay! Thanks @chriskrycho for following through.

[carols10cents]

YAYAYAYAY!! @chriskrycho, are you going to send a PR to update the RFC template to have the "How do we teach this?" section? I can do it if you're busy, but didn't want to steal the glory from your hard work :)

[chriskrycho]

I can do it in a few minutes, actually!

[bluss]

Please edit the "Rendered" link in the message thanks.