Evaluating Crates

How do users evaluate crates to use in their own projects?

What is important?

• Published on Crates.io
• (Complete) Examples
• A good API feel
• Documentation (Crate/Trait/Struct level)
• A responsive maintainer

What is not important?

• Dependencies
• Word of mouth
• Talks/Presentations

These results were very surprising to me!

...wish more crates had?

• Support both Stable and Nightly
• Support Windows (Or mention it doesn't!)
• Examples for most features (see clap)
• Changelogs(!)
• "Works well with..."
• Justifications for `unsafe` blocks
• Performance notes
• NOT commiting on `master`

'Good'

• Serde
• Rocket
• Rayon
• Nom
• Diesel
• Clap
• Byteorder

'Bad'

• Iron (maintenance)
• Rocket (nightly)
• Tokio (docs)
• Futures (docs)
• gfx-rs (corner cutting)

Maintaining Crates

How do we create better crates?

What is prioritized?

• Published (70% ranked critical)
• API Feel
• Documentaion (Higher than when evaluating!)
• CI Builds (Not important when evaluating!)
• Tests
• Examples

Advertising

• Reddit (71%)
• Blog (35%)
• Forums (38%)
• Twitter (35%)
• IRC/Chat (28%)
• Meetups/Conferences (20%)

How can a crate help new users?

• Show a roadmap for new features
• Documentation
• Examples
• Metadata (for crates)
• Links to more about the subject matter (!!)
• Advice on how to get help
• Sample projects (big examples)

Honor roll: "Nothing. I don't care for noobs" AKA someone who doesn't want users.

What do maintainers need to work on?

• Better documentation
• More internal linking
  • Cited that it is hard/awkward to do with rustdoc
• Examples
• Fuzzing
• Tests
• Advertising
• Finishing the last mile / polishing the crate

Note: New Contributors

Be willing to mentor them and help them evolve PRs.

Goals Today

• Learn to improve our projects!
• Learn how others learn!
• Create lots of small, actionable improvements
• Perhaps find new users and contributors. :)
• Share new learnings with everyone else.

How we do it

• Pair up with an observer and a user
• User tries to find, learn about, and use observer's crate.
• User is tasked with (or makes up) a project to expand an example from the crate.
• User explains their internal monologue and thought process to observer. (Light prompting allowed)
• Observer can not help without being explicitly asked.
• Observer takes notes about stumbling blocks and confusing bits.
• After about 20-30 mins, we change partners again after a short group sharing period.