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
340
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
230
Understanding Documentation Systems - ConFoo Vancouver 2016
ericholscher
0
290
Understanding Documentation Systems
ericholscher
1
280
Documentation as Empathy
ericholscher
1
250
Introduction to Sphinx & Read the Docs Djangocon 2015
ericholscher
0
170
Announcing Read the Docs for Business
ericholscher
1
230
Write the Docs NA 2014 Introduction
ericholscher
0
160
Introduction to Sphinx & Read the Docs
ericholscher
3
500
Documentation Journey
ericholscher
1
120
Other Decks in Programming
See All in Programming
猫と暮らす Google Nest Cam生活🐈 / WebRTC with Google Nest Cam
yutailang0119
0
160
What's new in AppKit on macOS 26
1024jp
0
140
テスト駆動Kaggle
isax1015
1
510
PicoRuby on Rails
makicamel
2
140
Python型ヒント完全ガイド 初心者でも分かる、現代的で実践的な使い方
mickey_kubo
1
180
Webの外へ飛び出せ NativePHPが切り拓くPHPの未来
takuyakatsusa
2
580
AI駆動のマルチエージェントによる業務フロー自動化の設計と実践
h_okkah
0
210
Quand Symfony, ApiPlatform, OpenAI et LangChain s'allient pour exploiter vos PDF : de la théorie à la production…
ahmedbhs123
0
210
効率的な開発手段として VRTを活用する
ishkawa
0
150
技術同人誌をMCP Serverにしてみた
74th
1
680
RailsGirls IZUMO スポンサーLT
16bitidol
0
190
はじめてのWeb API体験 ー 飲食店検索アプリを作ろうー
akinko_0915
0
130
Featured
See All Featured
Automating Front-end Workflow
addyosmani
1370
200k
[Rails World 2023 - Day 1 Closing Keynote] - The Magic of Rails
eileencodes
35
2.4k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
7
740
StorybookのUI Testing Handbookを読んだ
zakiyama
30
5.9k
Building a Scalable Design System with Sketch
lauravandoore
462
33k
Producing Creativity
orderedlist
PRO
346
40k
A Modern Web Designer's Workflow
chriscoyier
695
190k
Practical Orchestrator
shlominoach
189
11k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
229
22k
Rails Girls Zürich Keynote
gr2m
95
14k
Building an army of robots
kneath
306
45k
How to train your dragon (web standard)
notwaldorf
96
6.1k
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