Rust docs team is no more(blog.rust-lang.org)
blog.rust-lang.org
Rust docs team is no more
https://blog.rust-lang.org/inside-rust/2020/03/27/goodbye-docs-team.html
45 comments
That feeling when you're done with writing documentation but you just can't shake the impulse to document that fact.
More so when we are in a time when people have the time to document things.
Not everyone has a bunch of free time right now. People working on software tend to be able to work from home.
That feeling when you're documenting that someone made a HN comment documenting the blog post that documented the completion of the documentation.
See, all you need for job security is to create a recursive documentation procedure.
Somebody should write this down!
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.
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.
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.
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.
Some years ago, I spent a time being such a docs expert. I was documenting an SDK for iOS and Android, so dealt with Obj-C and Java simultaneously. I had to converse a lot with the dev team to understand their thinking behind choices. What I didn’t expect—and somewhat stumbled into by accident—was that I essentially became the person who spotted the myriad ways in which the iOS and Android teams didn’t communicate or plan SDK features and interfaces together, and wound up guiding SDK development from a docs perspective. Each platform was nothing like the other. I recall a lot of long conversations wherein I exhaustively explained why class and function names (as well as results!) should match across both platforms. And it took way more time than I thought it should—but I remember the light bulb moment when both the iOS team and Android team jointly realized there were devs out there who might want to build for both platforms, and would be frustrated if they had to learn the SDK twice. I became in that moment not just the guy who was writing all the developer docs, but the de facto lead for architecting and organizing the SDK itself, helping both teams plan together and create a consistent product. To me, it was second nature. To the other devs, they just didn’t think that way, and it took a lot for them to see the value (and let’s just ignore people who think code documents itself).
I share all that to say that I’m not sure it’s as easy to teach devs how to write good docs and continually care about doing that, as it is to have a docs expert become familiar with the code. Some people can do both, sure. Some can’t.
If doc experts really are worth their weight in gold, I wish I saw more job openings to come in, understand a code base, write Stripe-level documentation, and create a good doc culture. I’d do that job all day and never grow tired. I think good docs require a set of uncommon, non-programming skills—and I’m not sure the majority of teams are willing to sacrifice velocity to write good code, achieve total test coverage, and produce top-quality documentation.
I share all that to say that I’m not sure it’s as easy to teach devs how to write good docs and continually care about doing that, as it is to have a docs expert become familiar with the code. Some people can do both, sure. Some can’t.
If doc experts really are worth their weight in gold, I wish I saw more job openings to come in, understand a code base, write Stripe-level documentation, and create a good doc culture. I’d do that job all day and never grow tired. I think good docs require a set of uncommon, non-programming skills—and I’m not sure the majority of teams are willing to sacrifice velocity to write good code, achieve total test coverage, and produce top-quality documentation.
Did I read that wrong? It didn't sound like a 'switch'. It sounded more like someone quitting out of frustration and docs now ad-hoc with no clearly organized responsibility
It didn't sound like quitting to me, it was more like syncing the organization on paper with the reality. The team was one person and that person will continue what they do, only there's no reason to call it a team.
I think both approaches work well in some circumstances. The main issue with the "docs expert" approach is scalability. It's just harder to get enough of them. While I agree with you that the code author has said familiarity, a good docs person will be able to get that kind of information out of them.
The headline sounds scary, but the actual change sounds like it's merely an organizational reshuffling formality.
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.
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.
> 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.
They used to, but it looks like that came with its own set of problems: https://words.steveklabnik.com/thank-u-next
I know... dotnet and Go aren't exactly hurting for effort for things like docs and tooling that take a project from good to great.
shame, I'm that weirdo that actually loves reading and writing docs.
If moz were paying, I'd happily sit and just rummage through the codebase adding docs to everything.
That said I think Django had the best policy on this. Rather than get someone to write docs, make docs a first class citizen. i.e No matter how good your code is, if you don't update/create the relevant docs your PR doesn't pass muster.
As a result Django has some of the best documentation out there with only Symfony's docs coming anywhere close.
If moz were paying, I'd happily sit and just rummage through the codebase adding docs to everything.
That said I think Django had the best policy on this. Rather than get someone to write docs, make docs a first class citizen. i.e No matter how good your code is, if you don't update/create the relevant docs your PR doesn't pass muster.
As a result Django has some of the best documentation out there with only Symfony's docs coming anywhere close.
Rust is an amazing language, and I'm glad to see they are transparent too.
An example of a project that is "done?"
"done" in what sense? I don't think documentation of a living project is ever finished.
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.
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.
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.
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.
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.
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.)
(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.)
Those are both core features of Rust, though, so any alternative implementation all but has to have them as that is the first thing anyone using it will be looking for.
Of course you need to have them, but there's no specification of their behavior, so your only hope at compatibility is reverse-engineering the existing implementation (or just reading its code).
Elixir?
José Valim, announcing the just-released Elixir v1.9:
… releases was the last planned feature for Elixir. We don’t have any major user-facing feature in the works nor planned. I know for certain some will consider this fact the most excing part of this announcement!
[1] https://changelog.com/news/the-elixir-language-is-now-featur...
… releases was the last planned feature for Elixir. We don’t have any major user-facing feature in the works nor planned. I know for certain some will consider this fact the most excing part of this announcement!
[1] https://changelog.com/news/the-elixir-language-is-now-featur...
I read it to be saying it's 'done' in the sense that their documentation is now in a good state, and so doesn't need special attention. Not to say documentation is exactly 'done', of course.
I found the post a bit unclear, but my interpretation was that they're officially ending the 'Rust docs team', and will be reducing their focus on documentation, maintaining it in a more ad-hoc way.
I found the post a bit unclear, but my interpretation was that they're officially ending the 'Rust docs team', and will be reducing their focus on documentation, maintaining it in a more ad-hoc way.
TeX
The day TeX is done will be a sad one.
Luckily, it still is at version 3.14159265 and not yet at version π (https://en.wikipedia.org/wiki/TeX#TeX82)
Luckily, it still is at version 3.14159265 and not yet at version π (https://en.wikipedia.org/wiki/TeX#TeX82)
Good work, docs team.
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.
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.
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.
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.
&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.
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.
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.
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/
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.
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.
Good strategy. By ensuring good documentation in the early stages, the community will likely follow.
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?
This has been the state of the world for the last ~year, so it should remain roughly the same as that, at least.