Tweet
Tweet

Slide 1

Slide 1 text

Eric Holscher PyCaribbean February 21, 2016 Python Documentation: past, present, & future

Slide 2

Slide 2 text

@ericholscher Who am I • Co-Founder of Read the Docs • Co-Founder of Write the Docs

Slide 3

Slide 3 text

@ericholscher Read the Docs • 30,000 projects • 4M builds • 400M pageviews, 20M a month • https://blog.readthedocs.com/read-the- docs-2015-stats/

Slide 4

Slide 4 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher

Slide 5

Slide 5 text

@ericholscher Python Projects we host • Virtualenv • Jupyter • Fabric • Requests • Sphinx • Pip • Scrapy • Boto • Celery • Pyramid

Slide 6

Slide 6 text

@ericholscher Non-Python projects We host • Bootstrap Datepicker • Sequelize ORM • Doctrine ORM • ASP.Net • PHPMyAdmin • CouchDB • Julia

Slide 7

Slide 7 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher

Slide 8

Slide 8 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher

Slide 9

Slide 9 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher 13 meetups on 2 continents

Slide 10

Slide 10 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Understanding the value of Writing documentation

Slide 11

Slide 11 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher You will be using your code in 6 months

Slide 12

Slide 12 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher You want people to use your code

Slide 13

Slide 13 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher It makes your code better

Slide 14

Slide 14 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher You want to be a better writer

Slide 15

Slide 15 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Past

Slide 16

Slide 16 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Ten Years Ago

Slide 17

Slide 17 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher

Slide 18

Slide 18 text

@ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher \chapter{Interesting Features} \label{hawaii:features} We have some neat \emph{new} \emph{features}. Code Example

Slide 19

Slide 19 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Eight Years Ago

Slide 20

Slide 20 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher

Slide 21

Slide 21 text

@ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Interesting Features ==================== We have some neat *new features* Code Example

Slide 22

Slide 22 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Sphinx’s worldview

Slide 23

Slide 23 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Files should be readable as plaintext

Slide 24

Slide 24 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Documentation should be easy to contribute to

Slide 25

Slide 25 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Markup language should be extensible

Slide 26

Slide 26 text

@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

Slide 27

Slide 27 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Five years ago

Slide 28

Slide 28 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher

Slide 29

Slide 29 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Read the Docs worldview

Slide 30

Slide 30 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Docs should live within Version Control

Slide 31

Slide 31 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Docs should work like CI, and always be up to date

Slide 32

Slide 32 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Docs should be reviewed and treated just like code & tests

Slide 33

Slide 33 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher To encourage an activity, make it as easy as possible

Slide 34

Slide 34 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Three years ago

Slide 35

Slide 35 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher

Slide 36

Slide 36 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Write the Docs Worldview

Slide 37

Slide 37 text

@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

Slide 38

Slide 38 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher We need a community of people who care about documentation

Slide 39

Slide 39 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher We need standards and best practices for writing documentation

Slide 40

Slide 40 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Documentation is a fundamental part of teaching and learning programming

Slide 41

Slide 41 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Documentation is Outreach

Slide 42

Slide 42 text

@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

Slide 43

Slide 43 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Present

Slide 44

Slide 44 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Python community has excellent documentation

Slide 45

Slide 45 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Python is the #1 teaching language partially because of quality documentation

Slide 46

Slide 46 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Documentation isn’t practiced & improved

Slide 47

Slide 47 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Translation is subpar

Slide 48

Slide 48 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher

Slide 49

Slide 49 text

@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

Slide 50

Slide 50 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Future

Slide 51

Slide 51 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Support CommonMark fully

Slide 52

Slide 52 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Documentation generation without importing code

Slide 53

Slide 53 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Better translation infrastructure

Slide 54

Slide 54 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Automated testing & validation

Slide 55

Slide 55 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher More community standards and best practices around docs

Slide 56

Slide 56 text

@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

Slide 57

Slide 57 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Documentation as a first class citizen in all so ware shops

Slide 58

Slide 58 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Recap

Slide 59

Slide 59 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Python has uniquely good documentation & tools

Slide 60

Slide 60 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher We need to continue to invest in our documentation culture

Slide 61

Slide 61 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher Being a better writer makes you a better developer

Slide 62

Slide 62 text

@ericholscher @ericholscher writethedocs.org @ericholscher writethedocs.org @ericholscher @ericholscher writethedocs.org @ericholscher @ericholscher You never know who might benefit from the documentation you write

Slide 63

Slide 63 text

@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

Slide 64

Slide 64 text

@ericholscher Thanks • eric@ericholscher.com • @ericholscher • Come talk to me around the conference