@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
@ericholscher
@ericholscher
writethedocs.org @ericholscher
writethedocs.org @ericholscher
@ericholscher
writethedocs.org @ericholscher
@ericholscher
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
Slide 19
Slide 19 text
@ericholscher
@ericholscher
writethedocs.org @ericholscher
writethedocs.org @ericholscher
@ericholscher
writethedocs.org @ericholscher
@ericholscher
Eight Years Ago
@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
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
@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
@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
@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
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
@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
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
@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
• [email protected]
• @ericholscher
• Come talk to me around the conference