Propose the docs team #1683
9 participants
Regarding whether rustdoc should be the responsibility of the docs team or the tools team: it seems to me that the docs team's focus is on the content of documentation itself, and so the team's involvement in rustdoc would be advisory, giving feedback from the perspective of experienced documentation authors.
@AndrewBrinker: My position on it was that the html/css part would be handled by the doc team and the rest by the tool team. That's more or less the current situation anyway.
| + | ||
| +I am not quantifying this exactly because it's not about reaching some specific number; adding someone to the team should | ||
| +make sense if someone is doing all of these things. | ||
| + | ||
| +# Drawbacks | ||
| +[drawbacks]: #drawbacks | ||
| + | ||
| +This is Yet Another Team. Do we have too many teams? I don't think so, but someone might. | ||
| + | ||
| +# Alternatives | ||
| +[alternatives]: #alternatives | ||
| + | ||
| +The main alternative is not having a team. This is the status quo, so the situation is well-understood. | ||
| + | ||
| +It's possible that docs come under the purvew of "tools", and so maybe the docs team would be an expansion | ||
| +of the tools team, rather than its own new team. Or some other subteam. |
|
I don't think so - I don't think the tools team have ever touched on a docs issue (other than the code of rustdoc).
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
|
nrc
and 1 other
commented on an outdated diff
| +[drawbacks]: #drawbacks | ||
| + | ||
| +This is Yet Another Team. Do we have too many teams? I don't think so, but someone might. | ||
| + | ||
| +# Alternatives | ||
| +[alternatives]: #alternatives | ||
| + | ||
| +The main alternative is not having a team. This is the status quo, so the situation is well-understood. | ||
| + | ||
| +It's possible that docs come under the purvew of "tools", and so maybe the docs team would be an expansion | ||
| +of the tools team, rather than its own new team. Or some other subteam. | ||
| + | ||
| +# Unresolved questions | ||
| +[unresolved]: #unresolved-questions | ||
| + | ||
| +Should we quantify the number of commits before you can get on the team? Or the amount of time? |
|
I can tell you first-hand that quantity of commits does not necessarily correlate to quality of contributions or level of commitment :P
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
|
nrc
and 1 other
commented on an outdated diff
| +# Alternatives | ||
| +[alternatives]: #alternatives | ||
| + | ||
| +The main alternative is not having a team. This is the status quo, so the situation is well-understood. | ||
| + | ||
| +It's possible that docs come under the purvew of "tools", and so maybe the docs team would be an expansion | ||
| +of the tools team, rather than its own new team. Or some other subteam. | ||
| + | ||
| +# Unresolved questions | ||
| +[unresolved]: #unresolved-questions | ||
| + | ||
| +Should we quantify the number of commits before you can get on the team? Or the amount of time? | ||
| + | ||
| +Rustdoc is a tool that's owned by the tools team, but the doc team makes | ||
| +significant contributions to it. Is it part of the tools team or the docs team? | ||
| +Maybe a backend-frontend split? Or maybe it just stays with tools? |
|
I'd prefer to leave it with tools - it is a tool that generates documentation, not a piece of documentation. Given that we are not super-strict about who r+s what, I don't think it will make a big difference in practice - certainly not enough to warrant a frontend/backend split. I agree. I'd also be fine saying rustdoc is "jointly owned", but @nrc is right in that in reality PRs will end up getting reviewed by the appropriate person no matter what!
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
|
Thanks for writing this up @steveklabnik, looks great to me!
This looks great to me, and I'm excited to codify what y'all have been doing into a formal team structure!
Regarding whether rustdoc should be the responsibility of the docs team or the tools team: it seems to me that the docs team's focus is on the content of documentation itself, and so the team's involvement in rustdoc would be advisory, giving feedback from the perspective of experienced documentation authors.
Maybe one way to formalize this is an expectation that RFCs or major discussions that affect the functionality or output of rustdoc should be tagged T-docs as well as T-tools (meaning both are needed to sign off).
@aturon, that seems like a reasonable expectation to me, although I'm not a team member so it's not really my place to accept extra work on their behalf.
| +in an advisory capacity: helping people who want better documentation for their crates to understand how to accomplish | ||
| +that goal. Furthermore, monitoring the overall ecosystem documentation, and identifying places where we could contribute | ||
| +and make a large impact for all Rustaceans. If the Rust project itself has wonderful docs, but the ecosystem has terrible | ||
| +docs, then people will still be frustrated with Rust's documentation situation, especially given our anti-batteries-included | ||
| +attitude. To be clear, this does not mean _owning_ the ecosystem docs, but rather working to contribute in more ways | ||
| +than just the Rust project itself. | ||
| + | ||
| +We will coordinate in the `#rust-docs` IRC room, and have regular meetings, as the team sees fit. Regular meetings will be | ||
| +important to coordinate broader goals; and participation will be important for team members. We hold meetings weekly. | ||
| + | ||
| +## Membership | ||
| + | ||
| +* @steveklabnik, team lead | ||
| +* @GuillaumeGomez | ||
| +* @jonathandturner | ||
| +* @peschkaj |
|
Not that I object to the list, but I don’t remember seeing this person contributing to the rust documentation. Are they an intern? Sorry, I forgot to reply to this. They are not, or at least, not that I'm aware of. They've been doing a lot of joint work with @jonathandturner , as well as doing stuff like organizing the Rust Doc Days, etc
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
|
I’m generally a proponent of this RFC, if only for ability to ping @rust-lang/docs.
| +> * Delegating reviewer rights for the subteam area. The ability to r+ is not limited to team members, and in fact earning r+ rights is a good stepping stone toward team membership. Each team should set reviewing policy, manage reviewing rights, and ensure that reviews take place in a timely manner. (Thanks to Nick Cameron for this suggestion.) | ||
| + | ||
| +The first two are about RFCs themselves, but the second two are more pertinent to documentation. In particular, | ||
| +deciding who gets `r+` rights is important. A lack of clarity in this area has been unfortuante, and has led to a | ||
| +chicken and egg situation: without a documentation team, it's unclear how to be more involved in working on Rust's | ||
| +documentation, but without people to be on the team, there's no reason to form a team. For this reason, I think | ||
| +a small initial team will break this logjam, and provide room for new contributors to grow. | ||
| + | ||
| +# Detailed design | ||
| +[design]: #detailed-design | ||
| + | ||
| +The Rust documentation team will be responsible for all of the things listed above. Specifically, they will pertain | ||
| +to these areas of the Rust project: | ||
| + | ||
| +* The standard library documentation | ||
| +* The book and other long-form docs |
|
I'm assuming that "book" here is referring to TRPL and not rust-lang/book. Is that a correct assumption or do you see the docs team also contributing to the latter? rust-lang/book is the second version of TRPL, so they're really the same thing
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
|
| + | ||
| +It's important to have a path towards attaining team membership; there are some other people who have already been doing | ||
| +docs work that aren't on this list. These guidelines are not hard and fast, however, anyone wanting to eventually be a | ||
| +member of the team should pursue these goals: | ||
| + | ||
| +* Contributing documentation patches to Rust itself | ||
| +* Attending doc team meetings, which are open to all | ||
| +* generally being available on IRC to collaborate with others | ||
| + | ||
| +I am not quantifying this exactly because it's not about reaching some specific number; adding someone to the team should | ||
| +make sense if someone is doing all of these things. | ||
| + | ||
| +# Drawbacks | ||
| +[drawbacks]: #drawbacks | ||
| + | ||
| +This is Yet Another Team. Do we have too many teams? I don't think so, but someone might. |
|
As long as there are enough members to make up a team, and the responsibilities of the team don't overlap with existing teams, seems like it won't hurt to add another team.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
|
| +to these areas of the Rust project: | ||
| + | ||
| +* The standard library documentation | ||
| +* The book and other long-form docs | ||
| +* Cargo's documentation | ||
| +* The Error Index | ||
| + | ||
| +Furthermore, the documentation team will be available to help with ecosystem documentation, in a few ways. Firstly, | ||
| +in an advisory capacity: helping people who want better documentation for their crates to understand how to accomplish | ||
| +that goal. Furthermore, monitoring the overall ecosystem documentation, and identifying places where we could contribute | ||
| +and make a large impact for all Rustaceans. If the Rust project itself has wonderful docs, but the ecosystem has terrible | ||
| +docs, then people will still be frustrated with Rust's documentation situation, especially given our anti-batteries-included | ||
| +attitude. To be clear, this does not mean _owning_ the ecosystem docs, but rather working to contribute in more ways | ||
| +than just the Rust project itself. | ||
| + | ||
| +We will coordinate in the `#rust-docs` IRC room, and have regular meetings, as the team sees fit. Regular meetings will be |
|
Not sure how nitpicky you want to be here, but it might be good to specify the IRC server here
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
|
I've removed the "unresolved questions" as it seems they're resolved, from this discussion
This RFC proposes creating a new subteam for docs.
Rendered.
r? @rust-lang/core