2018 roadmap planning

[QuietMisdreavus]

A few weeks back we had a bit of a discussion of what we would try to focus on as a team in 2018. With the core 2018 roadmap under discussion right now, it's worth pulling out our own goals and tying them to the core roadmap.

From the meeting notes and IRC logs from 2018-01-09, we seemed to agree on some or all of the following:

• Bring the rustdoc rewrite to a point where it can be used as a viable everyday tool.
• Expand the docs team and team peers to get more people dedicated to documentation.
• Build up materials for Rust users who have graduated beyond The Rust Programming Language (TRPL) or Rust By Example (RBE), but don't feel experienced enough to run out and design their own systems. (i.e. "docs for intermediate-level Rustaceans")
• Organize some outreach to major libraries and frameworks to expand and polish their documentation.

---

To tie in the 2018 core roadmap, here's the current summary of that RFC:

This RFC sets the Rust 2018 Roadmap, in accordance with RFC 1728. This year's goals are:

• Ship an epoch release: Rust 2018.
• Build resources for intermediate Rustaceans.
• Connect and empower Rust’s global community.
• Grow Rust’s teams and new leaders within them.

In pursuing these goals, we will focus particularly on four target domains for Rust:

• Network services.
• WebAssembly.
• CLI apps.
• Embedded devices.

Taking the key goals one-by-one:

• Rust 2018
  • The key thing here is the focus on stabilizing items that are already implemented. As these items mature and land, they need documentation of their own (which should already exist in the Unstable Book >_>) and also integrating them into existing related docs like the Reference/TRPL/RBE, so that these documents are ready for the 2018 epoch alongside the rest of the language and libraries.
• Intermediate docs
  • This is basically our home field, and is directly tied to our discussions prior to the roadmap's initial planning. Even if we're directly not the ones to pen the docs in question, we'll still need to spot them, polish them, and pull them into an official standing.
  • Shortly after the 2018-01-09 docs team meeting, i had some discussions with the community and wrote up some ideas for possible avenues to take this. Taking a couple of these and giving them a good focus would be phenomenal.
  • Courtesy of @alercah, the Go code review guidelines are a good resource to emulate. They collect several small frequent comments that occur in review in the Go compiler repo, so they're a decent set of style and structure guidelines they've built up.
• Empowering the global community
  • While this is mainly led by the community team, we can still help out! For Rust to have a global user base, we need to keep an eye on docs in non-English languages, and helping people translate docs and giving them the tools to make them easily available.
  • While not a panacea, stabilizing rustdoc's ability to pull API docs from external files will help with extracting them for translation and swapping them out for a translated doc set.
• Expanding Rust's teams and leadership
  • This is connected to our own plans to create more Docs Team Peers and expand the team in general. Publicizing the team some (and formally announcing the peers! >_>) may help us grab some people who want to contribute to the Rust projects, but may otherwise not feel like jumping straight into the code.
• Domain focuses
  • The remaining notes in the summary talk about some "target markets" to guide the rest of the development. Something i personally noticed is that all of these domains have already generated a lot of community involvement and momentum behind them. It would be important to be able to at least keep a sense of what the available resources are for a given domain, like how Hello Rust is keeping track of the WebAssembly work happening within and beyond the Rust repo.
  • This can also tie into our own idea of community docs outreach. If we choose to focus on one or more of these domains for our outreach event(s), we can strengthen these stories when Rust 2018 ships.

[QuietMisdreavus]

For the "intermediate docs" point, it's worth noting that one of my ideas - a book of design patterns - has existed for a while, though only partially completed and currently only as a listing of names with isolated explanations.

[steveklabnik]

@alercah had mentioned on IRC that one aspect of the RFC draft as written that's not super great is the total lack of mention of the reference. might be some good tweaks possible about how we're expanding in all ways, not focusing on RBE.

[QuietMisdreavus]

Good point! Has anyone mentioned this in the comment thread? I couldn't see anything in a quick scan. If not, i can leave a comment to that effect.

[GuillaumeGomez]

If possible, could we insist on tests this year? I feel like we went through a lot of shadow bugs last year and I'd like to reduce this as much as possible in the future. :)

[alercah]

I also mentioned in IRC that code review guides like Go's are excellent as an educational tool, since they teach style in byte-sized pieces as well as being a good reference for code reviewers trying to bring new coders up to speed.

[QuietMisdreavus]

@alercah Thanks for the reminder! I've added that link to the OP.

@GuillaumeGomez I'm not sure how well that sticks out as a guiding goal for the whole year? Like, we definitely should add tests to rustdoc, but that seems more like a project to organize out of the issue you already filed for this, rather than something to lift as a very public goal in the same vein as the core team roadmap.

[hjr3]

I believe one of the goals of the rustdoc rewrite was to make it easier to contribute. That compliments the goal of expanding the team as it will be easier to onboard people.

[steveklabnik]

I've updated the RFC: aturon/rfcs#14

Please weigh in!

[hjr3]

I wonder if we need a more descriptive name for Intermediate Documentation. Maybe something like Competent User Documentation, though I do not love that either. I fear it will not be obvious what we mean by Intermediate Documentation.

Also, I do not think that https://github.com/aturon/rfcs/pull/14/files?diff=split#diff-1c2d6aba093cfb7e02ac5e1597207c41R178 provides enough information about what the plan is for such documentation. Maybe something like:

The plan for this type of documentation is mostly "expand the bookshelf with resources for people who are comfortable with the basics of Rust but do not consider themselves advanced". The focus will be on helping people understand the big picture and could include topics around idiomatic Rust, design patterns and language features. This also ties into the "domain focuses" goal below, see that for more.