Hello and Welcome: Documentation in the Rust Ecosystem

Transcript

1. Hello and Welcome Documentation in the Rust Ecosystem (By Andrew Brinker)
2. How you say hello Act One
3. What does the word “Docs” include?
4. The Meet cute the black triangle the walkthrough the reference
5. The Meet Cute “What is this?” “Why should I care?”
6. The Black Triangle The simplest code to do something good
7. The Walkthrough explain like you’re in the room
8. The Reference the complete api & every explanation
9. Docs are the first thing people see
10. First impressions are important
11. good Docs are needed for productivity!
12. Frequently asked questions Act Two
13. Three phases
14. Community Outreach
15. Reach as far as possible
16. Take All Input seriously
17. Check for existing sources
18. The First Draft
19. You don’t need to know everything
20. It’s Okay to write poorly
21. Some docs are better than no docs
22. Refinement
23. Don’t fear the delete key
24. Get outside opinions
25. Listen
26. In The End Total time: ≈ 4 months Total comments: 416 Total commits: 42 Number of participants: 29 And it’s still not done!
27. Good docs… • Require empathy • Require collaboration • Require time • Don’t happen on accident
28. Docs in the Rust ecosystem Act Three
29. So many crates! Number of crates 6,639 Number of downloads 79,771,988 (As of October 24th at 7:08pm PST)
30. How Are the docs? Quality % of top 100 crates No docs provided 25% Poor quality 13% Fair quality 15% Good quality 47%
31. They’re Pretty Good!
32. But there’s room for improvement
33. Lots of docs are incomplete
34. Lots of docs don’t explain enough
35. Good news, Everyone!
36. The foundation is already laid
37. The rust project cares about docs!
38. Rustdoc is good, and getting better!
39. It’s a question of focus and planning
40. where do we go from here? Act Four
41. crate developers
42. Review your docs portfolio
43. Offer mentored docs issues
44. Treat docs contributors like code contributors
45. consider “doc days” or “doc sprints”
46. crate users
47. report docs issues when you have them
48. Participate in docs discussions
49. contribute docs improvements
50. Everyone
51. Let’s make rust more welcoming and productive together
52. Questions?