The New Docs Team Charter

[djc]

Suggestion of something I don’t exactly see covered: in terms of reference documentation, while the std is obviously an important part of this, I’ve been hoping there would be more reference material about the language. That is, we have the book to explain some things, but it likely doesn’t make sense to, for example, contain full coverage of all corners of the language, including the type system (like the orphan rule, coherence, specialization) and other aspects of using Rust that are not the libraries.

[QuietMisdreavus]

Suggestion of something I don’t exactly see covered: in terms of reference documentation, while the std is obviously an important part of this, I’ve been hoping there would be more reference material about the language. That is, we have the book to explain some things, but it likely doesn’t make sense to, for example, contain full coverage of all corners of the language, including the type system (like the orphan rule, coherence, specialization) and other aspects of using Rust that are not the libraries.

IMO, this is the purpose of the Reference, and supplemental material such as the Nomicon can help fill in for situations where the Reference may not be complete. These things are not outside the scope of the Docs team, though it also helps when we can collaborate with other teams to ensure that everything is accurate. For example, the Lang team formally decided to help complete the Reference this year as a roadmap priority.

And i would say that we have stuff this covered in likes like this one:

By docs and learning materials we don’t only mean API documentation but all officially sanctioned learning material related to Rust. This includes but is not limited to existing material such as “the book”, books related to Rust tools (e.g., the Cargo book), documentation around the compiler and writing unsafe code and other learning material media that does not yet exist including video and audio material.

[mrec]

Does being in charge of “the book” include the mdBook project used to build it? It’s been languishing a bit lately.

[SimonSapin]

Should we have a dedicated website?

I think the answer to literally this question is: there’s already one, https://doc.rust-lang.org/. So the question might be: should that landing page be restructured? (To add new content, to link to more external resources, …)

[steveklabnik]

I want to thank the members of the docs team @steveklabnik, @GuillaumeGomez, @QuietMisdreavus and @celaus for helping me put this together.

Thanks for putting this together, Ryan!

Does being in charge of “the book” include the mdBook project used to build it? It’s been languishing a bit lately.

The docs team is focused on writing words, not code. mdBook has languished, but we’re working separately on fixing that.

[olivia]

I would love if we could organize Rustlings under the docs team! That’d lift a small weight off my shoulders.

[Centril]

For example, the Lang team formally decided to help complete the Reference this year as a roadmap priority.

Yep. I think over time, the reference should move over to being primarily a T-Lang endeavor as the document that is transformed into a specification (and not “the advanced book”).

[Gankro]

has anyone on any of these teams actually determined what the boundary between the reference and the nomicon should be?

[Ixrec]

I can’t speak for any of those teams, but I always saw the Nomicon as “the unsafe Book”, in the sense that it is aimed at “newcomers” (who know what’s in The Book, but potentially nothing else), focuses on things that don’t matter in safe Rust, does not have to be strictly comprehensive, and pedagogical simplifications are allowed so it doesn’t have to be maximally strictly accurate all the time.

I would hope The Reference is supposed to be where every little detail or safe and unsafe Rust gets spelled out in “Rust standardese”, all text is considered normative (i.e. defines when alternative Rust compilers are buggy or just different) unless otherwise specified, and there’s a goal/expectation that “Rust standardese” should be comprehensible to anyone who’s read both The Book and The Nomicon. At least, that seems achievable to me, even though it’s obviously not where we’re at today.

[Centril]

all text is considered normative (i.e. defines when alternative Rust compilers are buggy or just different) unless otherwise specified

Normative including for rustc. The reference should eventually be sufficiently well specified that if there’s a difference between rustc and the reference, rustc is the part that should change.

and there’s a goal/expectation that “Rust standardese” should be comprehensible to anyone who’s read both The Book and The Nomicon.

I think this goal should be abandoned eventually as a hard constraint. It is cost prohibitive to have both a specification, that is sufficiently high-fidelity to be normative, and a separate reference text that can be understood by many users. Syncing these will be chaotic and will likely fail. Instead, the reference should feel free to intersperse prose text (which may be more understandable to users) with formal definitions of syntax, static semantics, and dynamic semantics in the usual forms (BNF, typing rules, operational semantics, …) as seen in The Definition of Standard ML and The WASM specification.

[steveklabnik]

I have personally always seen the reference as “the thing that will be the rust specification someday.”

As for the nomicon, it’s your take on the interesting, hard corners of Rust. Sorta how like the book is Carol and I’s take on teaching Rust.

[Centril]

As for the nomicon, it’s your take on the interesting, hard corners of Rust. Sorta how like the book is Carol and I’s take on teaching Rust.

Maybe there’s a need for a third thing: “The advanced rust book” to complement the book? – kinda like how you can read TaPL and then move on to ATaPL. So we have:

1. The book – introduction to Rust
2. The advanced book – move on to this when finishing 1.
3. The specifics collection:
   • nomicon (dark arts of unsafe) – written as a guide, not normative; can be read after finishing 1.
   • Some guide for proc macros…
   • edition guide
   • async book
   • … // insert your specific thing in expert guide form
4. The reference (specification) – bnf, typing rules, operational semantics, but also prose text. can be read in parts after 2/3 but likely needs familiarity with bnf/…

[steveklabnik]

Yes, I was originally planning on trying to tackle such a thing as of the end of the last year. I won’t be doing that now though, for lack of time.

[Centril]

I won’t be doing that now though, for lack of time.

Understandable – it happens when it happens, unless someone else wants to spearhead.

[mark-i-m]

One thing that I haven’t seen discussed: what is the docs team’s role regarding compiler documentation (e.g. rustc rustdocs and rustc-guide)?

I would personally love to see more involvement with maintaining rustc-guide and compiler rustdocs, and filling in (the many) gaps in documentation. Or does the docs team feel that these are not user-facing enough to fall under its purview?

[steveklabnik]

We just don’t have the members to be able to support it. If the team grows, that’d be great.

[chriskrycho]

Do we want to consider a re-branding from “docs” to “education” or something else?

I’d suggest “Learning Team” here—it covers docs and education nicely, and also clarifies that the focus here is not just writing documentation but helping people learn (including by helping other people who want to do teaching work).

That suggestion aside, mostly I just have for all of this.

[dcarosone]

I don’t really have a better word for it, and it might not really be the right word, but I’d like to suggest putting some more official emphasis on an editorial role or approach in the charter. Not in the sense of gate-keeping, and very much in the sense of facilitating, encouraging and enabling (as is very rightly already the approach emphasis). But still, I think there’s scope to be a bit more explicit about editorial-like roles that are currently impicit in the above, such as:

• discussing and deciding the structure, focus, tone and audience of various documents (and how they vary between each)
• generally weaving the threads of connectivity between and across the content that makes it feel cohesive, including perhaps replacing redundant or duplicated items with links
• setting some style guides and other documents-for-documenters that can help encourage the best possible contributions for the least process frustration on the part of both new writers and people merging PRs
• soliciting articles, sections and other relevant contributions to cover areas of need (including perhaps adaptations of things that started elsewhere as blog articles or in other formats)
• some curation, collection and highlighting of useful content elsewhere in the ecosystem

I don’t feel like anything above is particularly outside the stated goals, but deserves to be recognised as real work the team is likely to be doing.

[Ixrec]

If it matters, I 100% agree with those clarifications, I just didn’t want to write a massive essay to try and hedge against all possible misunderstandings like those.

[bogmihdav]

My 2c is that I would like more focus on The Ref. I don’t like it being a “best-effort document”.