Python Documentation: Past, Present, & Future

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

13 meetups on 2 continents

Understanding the value of Writing documentation

You will be using your code in 6 months

You want people to use your code

It makes your code better

You want to be a better writer

Past

Ten Years Ago

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

Eight Years Ago

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

Sphinx’s worldview

Files should be readable as plaintext

Documentation should be easy to contribute to

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

Five years ago

Read the Docs worldview

Docs should live within Version Control

Docs should work like CI, and always be up to date

Docs should be reviewed and treated just like code & tests

To encourage an activity, make it as easy as possible

Three years ago

Write the Docs Worldview

Documentation needs to be valued as much as code in the tech industry

We need a community of people who care about documentation

We need standards and best practices for writing documentation

Documentation is a fundamental part of teaching and learning programming

Documentation is Outreach

You don’t want a community full of people who don’t read documentation

Present

Python community has excellent documentation

Python is the #1 teaching language partially because of quality documentation

Documentation isn’t practiced & improved

Translation is subpar

Documentation is a becoming a standard part of any so ware project

Future

Support CommonMark fully

Documentation generation without importing code

Better translation infrastructure

Automated testing & validation

More community standards and best practices around docs

Technical Writers and other language communities will use our tools more and more

Documentation as a ﬁrst class citizen in all so ware shops

Recap

Python has uniquely good documentation & tools

We need to continue to invest in our documentation culture

Being a better writer makes you a better developer

You never know who might beneﬁt from the documentation you write

“I can’t say I’m self taught. I’ve been taught by the people who wrote the documentation” - @s0ulshake

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

Python Documentation: Past, Present, & Future

Python Documentation: Past, Present, & Future

More Decks by ericholscher

Other Decks in Programming

Featured

Transcript