I'm a newcomer to the Rust ecosystem, so please take my thoughts with a pinch of salt. That said, I must admit that I already have an application in production.
Documentation is one of the key factors that help a programming language gain traction and lower the entry barrier for newcomers. In most programming languages I've dabbled in, documentation is treated as a first-class citizen, with a strong emphasis on its importance—for code writers, readers, and end users alike.
Recently, I encountered a library with almost no documentation, which left me quite frustrated. There was hardly a working example, and when working with async code involving callbacks, I had to resort to trial and error with println!everywhere to figure out which callback was being called and when. I considered reaching out to the developer to request documentation but hesitated, feeling it wasn’t my place to make such demands. After all, this is open source—someone’s hard work and generosity—so I thought, "Either use it or leave it."
I ended up switching to a different library, only to find that it also lacked documentation. This time, I turned to ChatGPT for help, which led me down the proverbial rabbit hole. Since then, I've browsed a few other libraries with little to no documentation, and I can only hope this isn’t a widespread issue in the Rust ecosystem.
That said, I’ve also come across crates with exceptionally good documentation that made learning and integrating them an absolute pleasure. These examples highlight how great documentation can turn a challenging experience into an enjoyable one. To those crate authors who’ve invested in thorough documentation, thank you! Your work sets a high standard and is immensely appreciated.
I want to acknowledge that maintaining a crate is often a labor of love, and writing documentation requires both time and effort. The entire community, myself included, is deeply grateful to crate authors for their hard work in providing functionality that allows us to avoid reinventing the wheel.
That said, I’d like to encourage crate developers to take small steps toward improving documentation. A few practical suggestions include:
- Starting with a minimal
READMEthat covers installation, basic usage, and a simple example. - Using tools like
cargo docto auto-generate documentation for your public APIs. - Adding a contribution guide for those who might want to help improve the documentation.
Good documentation lowers the entry barrier for newcomers, increases crate adoption, encourages community contributions, and reduces support requests. It's a win-win for everyone in the ecosystem.
To all crate developers: Your work is deeply appreciated. Documentation is one more way to ensure your efforts make an even bigger impact.