Open Source & Feelings
Seattle
October 3, 2015
Documentation
as Empathy
Eric Holscher (@ericholscher)
Slide 2
Slide 2 text
7 years ago
Slide 3
Slide 3 text
I was writing Perl for the
Military
Slide 4
Slide 4 text
No
• Documentation
• Version Control
• Tests
Slide 5
Slide 5 text
It all started with a PDF
Slide 6
Slide 6 text
Serendipity
• Feb 20: http://ericholscher.com/blog/
2008/feb/20/job-hunt/
• Feb 21: https://jacobian.org/writing/
sailing-on/
Slide 7
Slide 7 text
Documentation Culture
Slide 8
Slide 8 text
People don’t use projects
that don’t have docs
Slide 9
Slide 9 text
I start writing docs
• Django Kong
• Django Test Utils
• Django Reusable App Docs
Slide 10
Slide 10 text
Jacob was a huge
influence
• 2009: https://jacobian.org/writing/great-
documentation/
• 2011: http://pyvideo.org/video/403/
pycon-2011--writing-great-documentation
Slide 11
Slide 11 text
Created Read the Docs to
reduce friction to writing &
publishing docs
Slide 12
Slide 12 text
From Tool
to Understanding
Slide 13
Slide 13 text
Read the Docs was started in
2010
Slide 14
Slide 14 text
No content
Slide 15
Slide 15 text
Started Write the Docs in
2013
Slide 16
Slide 16 text
Learned about a whole
community of writers
Slide 17
Slide 17 text
No content
Slide 18
Slide 18 text
Documentation is more than
a tool
Slide 19
Slide 19 text
Technical writers know
what makes so ware
understandable
Slide 20
Slide 20 text
More communities are
valuing documentation
Slide 21
Slide 21 text
Documentation as
guilt
Slide 22
Slide 22 text
Coding & Testing have
objective results
Slide 23
Slide 23 text
Documentation is a
“so skill”
Slide 24
Slide 24 text
All programmers feel guilt
about this
Slide 25
Slide 25 text
Leads to putting off
writing docs
Slide 26
Slide 26 text
We need to lower the
barriers in our industry to
writing documentation
Slide 27
Slide 27 text
Why it matters
Slide 28
Slide 28 text
Empathy
Slide 29
Slide 29 text
You don’t want a community
full of people who don’t read
documentation
Slide 30
Slide 30 text
Documentation is Outreach
Slide 31
Slide 31 text
No content
Slide 32
Slide 32 text
My path is the path of many
others
Slide 33
Slide 33 text
“I can’t say I’m self taught.
I’ve been taught by the people
who wrote the documentation”
— @soulshake