Skip to content

Commit 4139535

Browse files
authored
Merge pull request #1683 from steveklabnik/docs-team
Propose the docs team
2 parents 7e365b4 + 86ac17c commit 4139535

File tree

1 file changed

+105
-0
lines changed

1 file changed

+105
-0
lines changed

text/1683-docs-team.md

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
- Feature Name: N/A
2+
- Start Date: 2016-07-21
3+
- RFC PR: https://github.com/rust-lang/rfcs/pull/1683
4+
- Rust Issue: N/A
5+
6+
# Summary
7+
[summary]: #summary
8+
9+
Create a team responsible for documentation for the Rust project.
10+
11+
# Motivation
12+
[motivation]: #motivation
13+
14+
[RFC 1068] introduced a federated governance model for the Rust project. Several initial subteams were set up. There was a note
15+
after the [original subteam list] saying this:
16+
17+
[RFC 1068]: https://github.com/rust-lang/rfcs/blob/master/text/1068-rust-governance.md
18+
[original subteam list]: https://github.com/rust-lang/rfcs/blob/master/text/1068-rust-governance.md#the-teams
19+
20+
> In the long run, we will likely also want teams for documentation and for community events, but these can be spun up once there is a more clear need (and available resources).
21+
22+
Now is the time for a documentation subteam.
23+
24+
## Why documentation was left out
25+
26+
Documentation was left out of the original list because it wasn't clear that there would be anyone but me on it. Furthermore,
27+
one of the original reasons for the subteams was to decide who gets counted amongst consensus for RFCs, but it was unclear
28+
how many documentation-related RFCs there would even be.
29+
30+
## Chicken, meet egg
31+
32+
However, RFCs are not only what subteams do. To quote the RFC:
33+
34+
> * Shepherding RFCs for the subteam area. As always, that means (1) ensuring
35+
> that stakeholders are aware of the RFC, (2) working to tease out various
36+
> design tradeoffs and alternatives, and (3) helping build consensus.
37+
> * Accepting or rejecting RFCs in the subteam area.
38+
> * Setting policy on what changes in the subteam area require RFCs, and reviewing direct PRs for changes that do not require an RFC.
39+
> * 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.)
40+
41+
The first two are about RFCs themselves, but the second two are more pertinent to documentation. In particular,
42+
deciding who gets `r+` rights is important. A lack of clarity in this area has been unfortuante, and has led to a
43+
chicken and egg situation: without a documentation team, it's unclear how to be more involved in working on Rust's
44+
documentation, but without people to be on the team, there's no reason to form a team. For this reason, I think
45+
a small initial team will break this logjam, and provide room for new contributors to grow.
46+
47+
# Detailed design
48+
[design]: #detailed-design
49+
50+
The Rust documentation team will be responsible for all of the things listed above. Specifically, they will pertain
51+
to these areas of the Rust project:
52+
53+
* The standard library documentation
54+
* The book and other long-form docs
55+
* Cargo's documentation
56+
* The Error Index
57+
58+
Furthermore, the documentation team will be available to help with ecosystem documentation, in a few ways. Firstly,
59+
in an advisory capacity: helping people who want better documentation for their crates to understand how to accomplish
60+
that goal. Furthermore, monitoring the overall ecosystem documentation, and identifying places where we could contribute
61+
and make a large impact for all Rustaceans. If the Rust project itself has wonderful docs, but the ecosystem has terrible
62+
docs, then people will still be frustrated with Rust's documentation situation, especially given our anti-batteries-included
63+
attitude. To be clear, this does not mean _owning_ the ecosystem docs, but rather working to contribute in more ways
64+
than just the Rust project itself.
65+
66+
We will coordinate in the `#rust-docs` IRC room, and have regular meetings, as the team sees fit. Regular meetings will be
67+
important to coordinate broader goals; and participation will be important for team members. We hold meetings weekly.
68+
69+
## Membership
70+
71+
* @steveklabnik, team lead
72+
* @GuillaumeGomez
73+
* @jonathandturner
74+
* @peschkaj
75+
76+
It's important to have a path towards attaining team membership; there are some other people who have already been doing
77+
docs work that aren't on this list. These guidelines are not hard and fast, however, anyone wanting to eventually be a
78+
member of the team should pursue these goals:
79+
80+
* Contributing documentation patches to Rust itself
81+
* Attending doc team meetings, which are open to all
82+
* generally being available on [IRC][^IRC] to collaborate with others
83+
84+
I am not quantifying this exactly because it's not about reaching some specific number; adding someone to the team should
85+
make sense if someone is doing all of these things.
86+
87+
[^IRC]: The #rust-docs channel on irc.mozilla.org
88+
89+
# Drawbacks
90+
[drawbacks]: #drawbacks
91+
92+
This is Yet Another Team. Do we have too many teams? I don't think so, but someone might.
93+
94+
# Alternatives
95+
[alternatives]: #alternatives
96+
97+
The main alternative is not having a team. This is the status quo, so the situation is well-understood.
98+
99+
It's possible that docs come under the purvew of "tools", and so maybe the docs team would be an expansion
100+
of the tools team, rather than its own new team. Or some other subteam.
101+
102+
# Unresolved questions
103+
[unresolved]: #unresolved-questions
104+
105+
None.

0 commit comments

Comments
 (0)