I personally enjoy writing good documentation. Libraries aren’t complete without it IMO, and there are few things more satisfying than producing a complete library. A good API with good docs can read like a good story.
To a first approximation, I agree with the evaluation criteria. Specifically, the linked blog post provided some good context and I very much agree with the rationale there. To a second approximation, I’m not totally convinced that all sections need to be properly fleshed out. Specifically, smaller libraries probably don’t need long form docs. A solid module level introduction with good API docs and examples is usually enough in my experience.
I’d like to echo some of others’ thoughts on motivating documentation. In some ways, it’s a social problem. What can we do to provide positive reinforcement for writing good documentation? Others have mentioned some good ideas. I really like the idea of showcasing well documented crates, although this does imply some form of manual curation. I would personally consider it important enough to be mentioned in any introductory guide to crates.io. Something like: “If you want others to use your code, then increase the likelihood of them doing so by teaching them how to use your code.”
Also, I have personally come up with weird hacks to upload my docs to a web server somewhere. This saves me from having to do any kind of per-crate setup: all I have to do is add it to my “meta” Cargo.toml. But if this were done for me by Cargo/crates.io, then that’d be great.
I’d just like to say this I vehemently disagree that this is true. I’ve written a lot of Rust and I come across crates all the time that are just a pile of method signatures and traits and sub-module sprawl. I end up completely lost and uncertain how the author intends for me to use their code. In almost all cases, I end up having to read the source or the tests or find something that has that library as a dependency and use that as an example. Sometimes I can’t find these things or they aren’t enough, and in the end, I can’t be sure that I understand how to use the library correctly. This is not a Rust specific thing either.
I think my point here is: experienced Rust programmers need documentation too. We shouldn’t enable the “this crate is only for experts any way, so I don’t need to write docs” line of thinking.
OK, let me end on some positive notes:
- I think the single biggest roadblock to writing good documentation is having easy to use tools for doing so. I think that
rustdochas solved this problem to a large extent right from the get-go. This is so not true in other ecosystems (to the extent that I’ve written my own documentation generators). There is tons of room for improvement of course, but I just want to echo that one of the major problems other ecosystems face is not present here. That’s a really wonderful achievement.
Cargo.tomlputs documentation at the front of the picture by showing links to docs. This helps let everyone know that we care about docs and you should too.
- Providing a way to run tests inside documentation is wonderful because it gives us a way to show examples that we can be confident are correct.
I wonder, do we have a guide anywhere on “how to write docs for Rust crates”? I can think of a few things to say on that subject… (Document your type variables gosh darn it!)