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.
The headline sounds scary, but the actual change sounds like it's merely an organizational reshuffling formality.
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.
Rust is an amazing language, and I'm glad to see they are transparent too.
An example of a project that is "done?"
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.
&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.
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?
no engineer gets hired for writing docs; engineers performance is not measured by docs; even if some do get hired, they won't get paid that well;
That feeling when you're done with writing documentation but you just can't shake the impulse to document that fact.