The Reference in 2019

I was pleased to see that the 2019 roadmap said that the Reference was going to be a priority this year, for both the language and documentation teams.

Is there progress to report? Are those two teams broadly satisfied with the state of the reference manual?


There is not significant progress to report. There have been a few folks who have been putting great work into the reference, but the joint team project that we hoped would happen ended up not happening.

1 Like

Is it too late to start that project? There is still some of 2019 left!

Similarly to a roadmap, it doesn't make sense to start a project if nobody is going to work on it.

People working on the reference are already working on it without any organizational framing, and they are not affiliated neither with the doc team nor with people responsible for making roadmaps and starting projects.


Not just that, but there are other reasons that this project didn't happen, and they're also why it's too late to start. I'll be posting something this week that will explain.


Why are you saying that it's too late? I thought there is no hard deadline.

I think Steve means that it's not likely to finish in 2019, so let's wait until we formulate a 2020 roadmap rather than start another initiative that doesn't get finished.


It's worth noting that while the reference has seen minor, but consistent, improvements, there are on-going specification efforts in for example:

  • The rustc-guide
  • The unsafe-code-guidelines
  • The grammar working group (wg-grammar)
  • Research work in e.g. Oxide (e.g. @awe et. al's work) as well as in the Rust Belt research.
  • wg-polonius and chalk involve spec work as well.

My hypothesis is that one reason the reference isn't in a better state right now is that the foundational work of specifying e.g. the abstract machine, and other parts of the language have not been done. When that's the case, we don't have anything to build on and so some stabilizations are just filed as issues.

While the on-going spec efforts aforementioned might not bear immediate fruits, I think they will eventually improve things a lot.


Did this eventually happen?

Not quite yet, there’s been some additional delays. I’ll be sure to post here when it does.

1 Like

Perhaps there's some information you can provide while whatever is delayed is still being delayed?

Really, what I'd like to know is whether whatever it is that means it's too late to start a project for improving the Reference also means a volunteer is in danger of wasting their time if they try to do some work on it.

1 Like

@steveklabnik how are things going on this front?

I took a long vacation and did nothing. Sorry! Soon...

No problem! Hope the vacation was fun! :slightly_smiling_face:

Okay, sorry for taking forever here folks, this has just been hard. My initial post said:

The reason that this hasn't happened is that the docs team has been effectively dead for a long time, and we are finally actually making that official:

Additionally, @petrochenkov, @mark-i-m, and @Centril were all right about different things in different ways: there's no point in starting a huge project super late in the year, both due to roadmap issues as well as that work always slows down around the holidays. There weren't a lot of folks that were actually going to do this work, and there are folks who have been putting in great work on the reference without this being some official big project. Finally, there is just some foundational stuff that's not quite nailed down yet, and so isn't really ready to be documented yet.

If you're interested in contributing to the reference, please do: it still needs help, and there is still a lot of work to do. And folks working on it. Just this plan hasn't worked out so far.


@steveklabnik Thank you for your documentation efforts over the years. I agree with comments made on that PR (that a cross-discipline single-documentation team doesn't really work long-term) but I really hope you and some of the original team might stick around to help ensure that the voice of the documentation continues to be consistent -- that consistency was key to the success of the Rust documentation IME and I'd love to see it go on.


This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.