The New Docs Team Charter

#1

Hey all,

Below is the new charter for the docs team. The team plans on continuing with its previous responsibilities but hopes to expand into more areas of documentation and learning materials. If you’re interested in making the process of learning and using Rust at all experience levels better through a wide and diverse set of learning materials, please get in contact with us here or by email: docs@rust-lang.org.

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

Docs Team Charter

The docs team has until this point been primarily in charge of the standard library documentation and “the book”.

Going forward we propose to expand the charter of the Docs Team to include helping with all officially sanctioned learning materials. As we’ll explore in more detail below this does not necessarily mean creation of this learning material but rather providing help to those who wish to create the material themselves.

Mission

To facilitate the learning of the Rust programming language and related tools through both creating a diverse set of learning material and helping others produce such material.

Main Goals

  • Have up-to-date reference documentation
  • Create and promote official content across media
  • Promote content creation from other teams

The docs team focus is the facilitation of the creation and dissemination of official documentation and learning materials. We will achieve this by facilitating and promoting contributions by contributors and subteams as well as creating content ourselves. These materials can span across different media so Rust has a rich repository of materials suitable for people with diverse learning styles. We welcome library owners to collaborate with us on how to make more effective documentation and learning materials for their crates.

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.

Non-Goals

This team is not:

  • Gatekeeping “official” content or even docs creation
  • Replacing or competing with content creation from other teams
  • Taking over documentation efforts for 3rd party crates
  • Take over management or curation of community created learning materials

The team does not have a monopoly on creating material. For instance, the Cargo team is the most qualified group of people to contribute to the Cargo book, but the docs team should be responsible for helping with organization including but not limited to triaging issues, helping set high level content goals, doing reviews and helping recruit contributors.

This also does not mean that the docs team is the only team capable of creating new material. For instance, the latest effort from the compiler team to create videos explaining rustc internals should be encouraged by the docs team. The docs team, however, should make itself available to help with the effort.

While we want to help the entire community make better documentation and learning material, we are an extremely small team. We do not intend to assume documentation responsibility for any crates outside of the core of the language. However, as time permits, we’d love to work more closely with the community on making documentation across the ecosystem richer and more consistent.

Finally, the docs team does not want to get in the way of community members efforts in creating great learning material on their personal blogs, YouTube, Twitch and other platforms. We welcome collaboration with the community team in such efforts, but we do not see this as core to our responsibilities.

Possible Organization

  • Std Docs
    • Small team in charge of making sure the std library is completely documented.
  • Books
    • In charge of “the book” as well as helping other book efforts in ways illustrated above.
  • New Media
    • In charge of exploring new media (e.g., video) as a means of documentation and learning

Roadmap

  1. Establish good relationships with other teams and see if and how we can help with their learning material.
  2. Setup easy editorial pipeline and plan for more easily facilitating docs creation (i.e., make it trivial to contribute docs changes).
  3. Establish an easy to understand and digest plan for remaining work for stdlib docs.
  4. Create plan for non-traditional media creation such as audio and video.

We are currently a small team so we might not get to everything we would like to. Our number 1 priority is to continue to deliver high quality stdlib documentation and to ensure “the book” continues to be kept up to date. Once we feel confident we can continue this service, we’ll begin working on the expanded charter.

Unresolved Questions

  • Do we want to consider a re-branding from “docs” to “education” or something else?
  • What kind of campaigns do we want to consider?
    • Campaigns can be a good way to get people involved and to have people try their hands at different to see if something sticks. The more variety of activities we offer the more likely people are to find something they like.
  • Should we have a dedicated website?
    • Having a dedicate place to learn Rust (through a variety of media) and a place to contribute back to this effort could help.
10 Likes

#2

Yes! Speaking as someone that is learning Rust, I would love this (I’m currently doing a lot of exercises at exercism, but sometimes simply getting it right isn’t enough and Rust doesn’t have that many mentors over there).

There is a lot of content on Rust, blog posts and all that stuff that would be really nice to have an index of, as well. Rust seems to appeal to people from everywhere (web, systems, gaming) and having dedicated resources for different types of people would be amazing as well. The Book is great and it helped me a lot, but I think this would be great :slight_smile:

0 Likes

#3

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.

3 Likes

#4

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:

0 Likes

#5

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

0 Likes

#6

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, …)

0 Likes

#7

Thanks for putting this together, Ryan!

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

0 Likes

#8

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

2 Likes

#9

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”).

0 Likes

#10

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

1 Like

#11

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.

1 Like

#12

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.

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.

4 Likes

#13

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.

2 Likes

#14

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/…
4 Likes

#15

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.

0 Likes

#16

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

0 Likes

#17

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?

0 Likes

#18

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

2 Likes

#19

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 :revolving_hearts: for all of this.

0 Likes

#20

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.

2 Likes