4 ms·
(Author here.) I wrote this piece hastily, and it really wasn't intended for this broad of an audience — I won't redact the existing wording I still think it's
by brandur 9y ago
(Author here.)
I wrote this piece hastily, and it really wasn't intended for this broad of an audience — I won't redact the existing wording I still think it's roughly right, but I do regret a lot of it.
Rust's docs are amazing in certain contexts — the book is great, the built-in support for documentation on types/functions/etc. is amazing, and compiling code examples are a very laudable idea.
What I'm speaking to here is more once you get into the broader ecosystem and start using a lot of non-core libraries. Oftentimes I found that the front page docs explaining the basic premise were concise and well-written, but that things got quite a bit harder when you started diving into individual classes and functions (put another way, as you started deviating from the happy path). This doesn't apply everywhere, but often the comments are very minimal and the documentation relies heavily on "types as documentation" in that there's a big list of all the traits and the functions on those traits that are implemented. In many, many cases there's little in the way of detail or examples.
I've written quite a bit of Rust now and have used many of the headliner projects. So far there have been very few crates where I didn't have to resort to eventually checking out the source tree and figuring out how to do some particular thing by examining its source code and test suite. I won't call out any single project in particular, but I found this to be the case in every one of `actix`, `clap`, `diesel`, `error-chain`, `horrorshow`, `hyper` and `juniper`, just to pick a few from the top of my `Cargo.toml` (it also happened with many other libraries). It's great that you can do this and open source is awesome, but ideally I could get by on just documentation, which is what you can do in many other languages.
Unfortunately, read with little context, it sounds like the tone of my piece was intended to crucify, but it's not. It can be simultaneously true that Rust's docs can still use lots of improvement and that the Rust team is doing an amazing job of improving them (there's just a lot of work and a long way to go). Both these facts are true with Rust.
- burntsushi 9y ago> (it also happened with many other libraries) I take documentation bugs seriously. If you did this with any of my crates, please file bugs. My guess is that other crate authors might feel the same, and that they would also appreciate bug reports. Writing good docs is super hard, because in order to do it well, one must sink themselves entirely into the perspective of someone who is seeking answers. This is hard when you already have the answers.
- brandur 9y ago> I take documentation bugs seriously. If you did this with any of my crates, please file bugs. My guess is that other crate authors might feel the same, and that they would also appreciate bug reports. Will do! For what it's worth, I also had `chan` in dependencies list, but didn't list it above because it's one of the minority where the docs and examples were very good. More generally, I feel quite bad for complaining about things instead of going in to improve them (through bug reports or patches), but there has to be a balance between making forward progress and stopping to help shore up the tooling. That said, I haven't been doing enough of the latter lately, so I'll make more of an effort.
- burntsushi 9y agoYeah, totally, I hear you. I certainly don't file issues for everything I should either. Mostly, my aim was to make it clear that documentation is one of my priorities. It isn't everyone's priority, so some might think that filing documentation bugs isn't wanted or something. But they definitely are, for me at least!
- UncleEntity 9y ago> What I'm speaking to here is more once you get into the broader ecosystem and start using a lot of non-core libraries. Don't even know how many times I've had to dig into the python sources to figure out why something wasn't working as intended... My favorite: I was trying to get memory buffer working for an object (following the official docs) using the C-api and it just didn't work no matter how much I fiddled with it so I go digging through the python sources and find out the fully documented feature I was attempting to use wasn't even implemented. Well, half the PEP was implemented. I'm probably just funny that way since if I can't figure something out from docs I just go read the sources.
- wokwokwok 9y agoI wonder idly if it would be useful to have 'cargo doc deps' that would generate docs for all your dependencies (or top level dependencies) in a project. The rust docs are super useful, but not everyone bothers to publish them, and people tend to forget to pit full working examples in them.
- dbaupp 9y ago'cargo doc' generates documentation for dependencies (along with the main crate) by default.
- deleted 9y ago[deleted]
- fafhrd91 9y agoWriting good docs is hard for sure! Especially for developers, you just want to write cool code :) but take into an account lifetime of the projects, compared to python all of them pretty young. For example I started actix-web just 5 months ago, sure it needs more documentation