41–46 of 46 posts
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?
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 wit…
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.
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 wit…
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.
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.
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.
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.