Rust docs team is no more (opens in new tab)

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

That feeling when you're documenting that someone made a HN comment documenting the blog post that documented the completion of the documentation.

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.

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.

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

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.

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.

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.

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

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...

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.

TeX

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.

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