Documentation in the Rust Ecosystem

Rust Belt Rust:

Documentation is important. It lowers the barrier for newcomers to use and understand libraries. It helps train and prepare new contributors. It opens up avenues of contribution that go beyond writing code. It makes open source more open, and makes libraries better by its existence.

Rust has all the makings of a great ecosystem of well-documented libraries: a high-quality and ever-improving documentation generator ships with the compiler, and the language team leads by example with a strong focus on documentation. Yet the quality and availability of documentation for Rust crates remains spotty, with many crates providing incomplete documentation, or relying on the types they expose to describe their use and function. This talk takes an in-depth look at the state of documentation in the Rust ecosystem today—including how many crates provide easily-located documentation, and how complete that documentation is—and then describes ideas for improvement, including improvements to Rust’s documentation-related tools and ideas for crate maintainers to both write better docs themselves and to encourage contributions from others via documentation-focused mentorship.

View slides.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s