Python Documentation: Past, Present, & Future

1.

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

2.

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

3.

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

4.

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

5.

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

6.

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

7.


8.


9.

13 meetups on 2 continents

10.

Understanding the value of Writing documentation

11.

You will be using your code in 6 months

12.

You want people to use your code

13.

It makes your code better

14.

You want to be a better writer

15.

Past

16.

Ten Years Ago

17.


18.

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

19.

Eight Years Ago

20.


21.

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

22.

Sphinx’s worldview

23.

Files should be readable as plaintext

24.

Documentation should be easy to contribute to

25.

Markup language should be extensible

26.

@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

27.

Five years ago

28.


29.

Read the Docs worldview

30.

Docs should live within Version Control

31.

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

32.

Docs should be reviewed and treated just like code & tests

33.

To encourage an activity, make it as easy as possible

34.

Three years ago

35.


36.

Write the Docs Worldview

37.

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

38.

We need a community of people who care about documentation

39.

We need standards and best practices for writing documentation

40.

Documentation is a fundamental part of teaching and learning programming

41.

Documentation is Outreach

42.

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

43.

Present

44.

Python community has excellent documentation

45.

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

46.

Documentation isn’t practiced & improved

47.

Translation is subpar

48.


49.

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

50.

Future

51.

Support CommonMark fully

52.

Documentation generation without importing code

53.

Better translation infrastructure

54.

Automated testing & validation

55.

More community standards and best practices around docs

56.

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

57.

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

58.

Recap

59.

Python has uniquely good documentation & tools

60.

We need to continue to invest in our documentation culture

61.

Being a better writer makes you a better developer

62.

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

63.

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

64.

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

Python Documentation: Past, Present, & Future

Python Documentation: Past, Present, & Future

Want more?

Transcript