Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Python Documentation: Past, Present, & Future
Search
ericholscher
February 21, 2016
Programming
3
290
Python Documentation: Past, Present, & Future
My keynote at PyCaribbean about the history of Python's documentation culture.
ericholscher
February 21, 2016
Tweet
Share
More Decks by ericholscher
See All by ericholscher
Introduction to Django Channels - ConFoo Vancouver 2016
ericholscher
0
210
Understanding Documentation Systems - ConFoo Vancouver 2016
ericholscher
0
270
Understanding Documentation Systems
ericholscher
1
260
Documentation as Empathy
ericholscher
1
220
Introduction to Sphinx & Read the Docs Djangocon 2015
ericholscher
0
150
Announcing Read the Docs for Business
ericholscher
1
220
Write the Docs NA 2014 Introduction
ericholscher
0
140
Introduction to Sphinx & Read the Docs
ericholscher
3
380
Documentation Journey
ericholscher
1
110
Other Decks in Programming
See All in Programming
Jetpack for KMP
fornewid
1
290
入社1ヶ月でここまでやった!Findy Toolsインフラ支援の最適化
rvirus0817
6
1.4k
feature環境をGitHub ActionsとCloudFormationでいい感じに管理する
nealle
2
310
CSC307 Lecture 09
javiergs
PRO
1
500
CSC307 Lecture 14
javiergs
PRO
0
220
CSC307 Lecture 13
javiergs
PRO
0
150
AHC035解説
terryu16
0
730
Xcode 16のPreviewModifierと@Previewableを活用した効率的なプレビュー方法の考察
ojun9
2
160
英語
s_shimotori
1
220
GraphQL はいいぞ! ~Laravel で学ぶ GraphQL 入門~
azuki
1
160
しくじり先生 Image Matching Challenge 2024 編
goosehaaan
0
810
AWS CDKにおける「再利用性」を考える / aws-cdk-reusability
gotok365
6
1.3k
Featured
See All Featured
Understanding Cognitive Biases in Performance Measurement
bluesmoon
18
1.2k
Designing for humans not robots
tammielis
247
25k
Teambox: Starting and Learning
jrom
130
8.6k
Imperfection Machines: The Place of Print at Facebook
scottboms
262
13k
A Tale of Four Properties
chriscoyier
155
22k
Music & Morning Musume
bryan
43
5.9k
GitHub's CSS Performance
jonrohan
1026
450k
GraphQLの誤解/rethinking-graphql
sonatard
59
9.6k
How to Think Like a Performance Engineer
csswizardry
4
590
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
jcasabona
26
1.8k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
353
29k
Raft: Consensus for Rubyists
vanstee
134
6.5k
Transcript
Eric Holscher PyCaribbean February 21, 2016 Python Documentation: past, present,
& future
@ericholscher Who am I • Co-Founder of Read the Docs
• Co-Founder of Write the Docs
@ericholscher Read the Docs • 30,000 projects • 4M builds
• 400M pageviews, 20M a month • https://blog.readthedocs.com/read-the- docs-2015-stats/
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
@ericholscher Python Projects we host • Virtualenv • Jupyter •
Fabric • Requests • Sphinx • Pip • Scrapy • Boto • Celery • Pyramid
@ericholscher Non-Python projects We host • Bootstrap Datepicker • Sequelize
ORM • Doctrine ORM • ASP.Net • PHPMyAdmin • CouchDB • Julia
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
13 meetups on 2 continents
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Understanding the value of Writing documentation
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
You will be using your code in 6 months
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
You want people to use your code
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
It makes your code better
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
You want to be a better writer
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Past
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Ten Years Ago
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
@ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher \chapter{Interesting Features} \label{hawaii:features} We have
some neat \emph{new} \emph{features}. Code Example
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Eight Years Ago
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
@ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Interesting Features ==================== We have
some neat *new features* Code Example
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Sphinx’s worldview
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Files should be readable as plaintext
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Documentation should be easy to contribute to
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Markup language should be extensible
@ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher # Markdown Check out [PEP
8](https:// www.python.org/dev/peps/pep-0008/) # RST Check out :pep:`8` Markdown vs. RST
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Five years ago
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Read the Docs worldview
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Docs should live within Version Control
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Docs should work like CI, and always be up to date
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Docs should be reviewed and treated just like code & tests
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
To encourage an activity, make it as easy as possible
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Three years ago
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Write the Docs Worldview
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Documentation needs to be valued as much as code in the tech industry
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
We need a community of people who care about documentation
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
We need standards and best practices for writing documentation
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Documentation is a fundamental part of teaching and learning programming
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Documentation is Outreach
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
You don’t want a community full of people who don’t read documentation
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Present
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Python community has excellent documentation
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Python is the #1 teaching language partially because of quality documentation
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Documentation isn’t practiced & improved
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Translation is subpar
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Documentation is a becoming a standard part of any so ware project
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Future
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Support CommonMark fully
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Documentation generation without importing code
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Better translation infrastructure
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Automated testing & validation
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
More community standards and best practices around docs
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Technical Writers and other language communities will use our tools more and more
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Documentation as a first class citizen in all so ware shops
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Recap
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Python has uniquely good documentation & tools
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
We need to continue to invest in our documentation culture
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
Being a better writer makes you a better developer
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
You never know who might benefit from the documentation you write
@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher
“I can’t say I’m self taught. I’ve been taught by the people who wrote the documentation” - @s0ulshake
@ericholscher Thanks •
[email protected]
• @ericholscher • Come talk to
me around the conference