So, I haven't spoken with the docs team about all of this yet, given that it was just posted, but here's my own personal thought:
For the docs team, I would hope that we can manage to switch from reactive to proactive.
What do I mean by this? Well, ever since I came on board, I've been in 'reactive mode.' "Here's the language and standard library, get to work." Consider it like a consumer/producer problem:
The "producer" are people working on things: the language, libraries, etc. Once they've produced their code, it goes into the buffer. Then, the consumer is writing the docs: something gets popped off the queue, worked on, and documented.
The problem is, with many more producers than consumers, the buffer fills up. This leads to bugs like Ensure accepted RFCs are all in the manual and elsewhere · Issue #20137 · rust-lang/rust · GitHub, and you can see what happened there.
So, what to do? Well, now that it's not just me, I'm hoping that we as a group can finish off the backlog in the buffer. Once we do, we can stop fighting fires and start taking a more pro-active stance on docs. Some of that is tied into all the other goals, for example. So like, let's take one of them: FFI. We could have a whole little mini-book on FFI and Rust, and how to make it good. But I don't have time for that; the standard library still has functions with no docs. This would be the "proactive" mode: we're focusing on what docs the ecosystem needs to have, rather than just catching up on a huge backlog.
The next level is getting rid of the producer/consumer issue entirely: @chriskrycho opened RFC: Require documentation for all new features. by chriskrycho · Pull Request #1636 · rust-lang/rfcs · GitHub , which basically says "nothing can ever go into the buffer". In order to manage that, we as a team will have to help others help us, by getting more people to write docs, even if they don't usually write them. We want to keep high standards, yet not let that block actually shipping.
Now, for some replies:
Could you elaborate on what you mean here? What doesn't work about it?
I think this post by @wycats is a big part of it:
One argument passed for the hasher isn't short enough? What would be your ideal syntax here?