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
- Establish good relationships with other teams and see if and how we can help with their learning material.
- Setup easy editorial pipeline and plan for more easily facilitating docs creation (i.e., make it trivial to contribute docs changes).
- Establish an easy to understand and digest plan for remaining work for stdlib docs.
- 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.
-- it happens when it happens, unless someone else wants to spearhead.
for all of this.