
Rust docs team is no more - garyng
https://blog.rust-lang.org/inside-rust/2020/03/27/goodbye-docs-team.html
======
Traster
That feeling when you're done with writing documentation but you just can't
shake the impulse to document that fact.

~~~
Zenst
More so when we are in a time when people have the time to document things.

~~~
daveFNbuck
Not everyone has a bunch of free time right now. People working on software
tend to be able to work from home.

------
Townley
To get good documentation, you can either take a documentation expert (they
exist and they're worth their weight in gold) and teach them the relevant part
of the code base, or take the code author and teach them to write good docs.
In my opinion, the second approach is best because the code author has the
nuanced familiarity necessary to provide high-level context to an end-user.

This switch by Rust seems in line with that thinking. The Rust community,
through no accidents, has incredible standards when it comes to documentation.
Now that the feature teams have learned to write docs that live up to that
standard (a skill as valuable as writing tests IMO) it makes sense for them to
do so.

~~~
scottlamb
I think you need both. You're not going to get a documentation team to
successfully write API docs for every nook and cranny of the codebase if those
nook and crannies' respective coders are uninterested. But you're also not
going to get a bunch of coders whose main job is extending the language to
write the Rust Book on the side. To me good documentation means that both
those things exist.

~~~
dan_quixote
You absolutely need both for quality, public-facing docs. The process of
explaining the logic to your docs expert is just invaluable. Without the docs
expert, the engineer(s) is too in-the-weeds to meet the audience's needs
thoroughly. Without the engineer(s), the docs expert has too steep a hill to
climb to understand the intent and edge cases.

------
pornel
The headline sounds scary, but the actual change sounds like it's merely an
organizational reshuffling formality.

~~~
steveklabnik
Sort of! We'll see if the teams actually keep up the standards of the docs, or
if they slide. They've been doing a good job for a while, but it's also pretty
varied across the teams.

------
hu3
Begs the question: Why isn't Mozilla funding this?

> At this point, the only person really writing docs is me, and I haven't had
> a ton of time lately either. So we haven't had a docs team meeting since
> August of 2018. There also aren't really docs RFCs these days. As such, this
> blog post isn't really announcing the end of the docs team as much as it is
> describing what is already true today.

~~~
saxonww
They used to, but it looks like that came with its own set of problems:
[https://words.steveklabnik.com/thank-u-
next](https://words.steveklabnik.com/thank-u-next)

------
hereisdx
Rust is an amazing language, and I'm glad to see they are transparent too.

------
mikece
An example of a project that is "done?"

~~~
hu3
"done" in what sense? I don't think documentation of a living project is ever
finished.

~~~
ocdtrekkie
Sure, but it sounds like docs are now updated by the relevant developers. The
"docs team" sounds more like a project team to overhaul the state of docs at
the time, which is now complete.

~~~
phkahler
We can hope that the language itself is similarly declared "done" at some
point. That would be in contrast to C++ for example, where it's the job of a
bunch of people to keep making changes ad nausium until it starts to crumble.

~~~
cwzwarich
Would a Rust spec that actually allows multiple compatible implementations
actually be simpler than the C++ spec? There has only ever been one real Rust
implementation, and a lot of Rust behaviors are just arbitrary implementation
decisions, especially with subtyping in the type system and the borrow
checker.

~~~
steveklabnik
mrustc has implemented a significant portion of the language, without a formal
spec. It's at least advanced enough to compile the compiler. The biggest
feature missing is borrowcheck.

~~~
cwzwarich
I don't mean a formal spec. Rust is much too complicated and asymmetric to
have a formal spec of the kind that exists for other languages (e.g. Standard
ML), at least using current specification methodology. It doesn't even have an
informal spec, which would be required to have a real attempt at multiple
compatible implementations.

~~~
steveklabnik
I hear what you're saying, but at the same time, mrustc is _almost_ a
counterexample of that. And we have real counterexamples in other languages
too; Ruby and Python, for example.

(My understanding of mrustc and borrowck is that it's not implemented because
the primary initial goal is bootstrapping rustc, not being a general rust
compiler.)

------
shadowgovt
Good work, docs team.

------
calibas
Sounds like a situation I've found myself in before. The majority of the work
is done, and it's become more work to organize and maintain a team than to
simply do it on your own.

------
weinzierl
The Rust documentation was not the reason I started with Rust but it was an
important reason why I stuck with it and it was what helped me over the
initial bump. The chapter about ownership and borrowing in the Rust Book was
particularly helpful and it was nice to see it evolve and improve over time.

------
prike
Respect to the Rust docs team.

Unfortunately, the rust std docs are not my favourite. I think i'm much more
comfortable in other's languages docs. I really like the examples, like in
c++.

Maybe I just don't know hot to use them.

------
mfer
&tldr; The docs team created filled in the gaps where they were needed when it
was created. Now, the teams making the code changes handle their own docs and
doc changes. There is no longer a need for a docs only team.

So, instead of having a dedicated team for docs the load has shifted to the
teams responsible for the code. Sounds like a reorg more than anything.

~~~
tannhaeuser
Out of curiosity, how many people are working on Rust as permanent employees
or otherwise paid by Mozilla? I thought Rust is mainly developed by individual
contributors but "load has shifted to the teams responsible for the code" and
"reorgs" sure sounds like there's some kind of hierarchical leverage and long-
term planning in place.

~~~
steveklabnik
Mozilla employs something like .... five? people to work on Rust these days.
We usually have a few hundred contribute to any given release
[https://thanks.rust-lang.org/](https://thanks.rust-lang.org/)

I left Mozilla over a year ago, this change isn't really super relevant to it
other than I was a full time docs person and now there are no full time docs
people. One person isn't a team, though, and the team had these issues even
when I was employed.

------
adrianhel
Good strategy. By ensuring good documentation in the early stages, the
community will likely follow.

------
throwawaysea
I'm not deeply familiar with how Rust is organized, but have found their
documentation to be useful when dabbling with it. Will they continue updating
docs at the same fidelity after this change?

~~~
steveklabnik
This has been the state of the world for the last ~year, so it should remain
roughly the same as that, at least.

