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

[bobwaycott]

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.

[scabarott]

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

[hiccuphippo]

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.

[steveklabnik]

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.