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