Hey everyone, The problem Last week, someone said that they ended up not using Rust because they were frustrated with the documentation. I asked some questions, and it turns out they didn't mean fro Rust itself: they meant that when they got out into the ecosystem, they got frustrated. So naturally…

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. :smile: To a first approximation, I agree with the evaluation criteria. Specific…

[image] BurntSushi: Well spoken as always. Something else that could be done for crates is having topic landing pages of some form. Take algebra for example (I've never used any of them). There are 34 crates over 4 pages. It's pretty unlikely that I'll even look past page 2 for something. I'l…

I violently agree with both @Manishearth (my Rust mentor, btw.) and @burntsushi (whose crates are gold standard in documentation). I wanted to add one point: discoverability and cross-crate linking. I find that the more connected (internally and externally) documentation is, the easier it is to fin…

I'm trying hard to write enough docs for Octavo that this would not only be fancy-new-crypto-lib but also I want it to be review of modern cryptography with long descriptions of algorithms. It should be almost book about cryptography, but I found some issues with current docs in progress: no way t…

[image] hauleth: no way to include math in docs. For the docs of one crate, I fed math into something that typeset expressions in KaTeX online, then did something similar: copied the generated HTML (plus all the requisite CSS) straight into the Markdown. It was impossible to maintain, and wa…

[image] hauleth: there should be indicator in Crates.io that show how much code is documented, this would help with choosing well done package. I really love this idea! Showing a percentage or a little progress bar next to each crate with the proportion of public items with at least some docs…

There's a lot of great ideas here! I'd like to bring up 1 specific example: From the serde page on crates.io you see two links, one for Documentation and another for Repository The landing page for the serde rustdocs is a bit lackluster, with only a brief introductory paragraph, and nothing at a…

I'd be interested in an indicator for #![deny(missing_docs]. :slight_smile:

[image] carols10cents: would you be willing to praise some particular crates or authors, maybe one from each type of documentation that earned a 5? This is a good idea! First Contact I gave a five to regex: [image] It's got it all: instructions on how to use it, a link to crates.io , an ov…

[image] johansigfrids: This is where I would advocate leading by example. I absolutely agree and think this is important. Hence why I'm trying to get started on this early. :slight_smile: but good point, yes!

Let's talk about ecosystem documentation

announcements

BurntSushi September 10, 2015, 1:44pm 24

I really love this idea! Showing a percentage or a little progress bar next to each crate with the proportion of public items with at least some docs would be a great starting point.

Topic		Replies	Views
Should rust force good documentation usages?	27	1469	January 8, 2024
Functions on docs.rs help	34	720	March 20, 2026
Blog post: Crate publishing tips and guidelines community	17	2352	June 16, 2020
Lib.rs (was Crates.rs) — what's next? community	79	8790	December 5, 2024
Crates.io curation community	31	3090	October 3, 2022

Let's talk about ecosystem documentation

Related topics