Write the Docs by James Bennett

Slide 1

Slide 1 text

Write the Docs James Bennett · PyCon US 2013 Santa Clara, California Friday, March 15, 13

Slide 2

Slide 2 text

Hi. Friday, March 15, 13

Slide 3

Slide 3 text

Friday, March 15, 13

Slide 4

Slide 4 text

Friday, March 15, 13

Slide 5

Slide 5 text

Friday, March 15, 13

Slide 6

Slide 6 text

Bradypus variegatus (brown-throated three-toed sloth) Friday, March 15, 13

Slide 7

Slide 7 text

SLOTH FACTS • Can extract energy from low-nutrition food sources • Multi-part stomachs (up to a month to digest!) • Native to Central and South America Friday, March 15, 13

Slide 8

Slide 8 text

Software users Friday, March 15, 13

Slide 9

Slide 9 text

Happy sloth (its name is Herman) Friday, March 15, 13

Slide 10

Slide 10 text

Happy users • Stay with you • Promote your software • Contribute to your software Friday, March 15, 13

Slide 11

Slide 11 text

0 25 50 75 100 Happy users Bad documentation Great documentation Friday, March 15, 13

Slide 12

Slide 12 text

You need great documentation Friday, March 15, 13

Slide 13

Slide 13 text

Make this happen Friday, March 15, 13

Slide 14

Slide 14 text

The one thing Friday, March 15, 13

Slide 15

Slide 15 text

Friday, March 15, 13

Slide 16

Slide 16 text

Remember the second sloth fact? Friday, March 15, 13

Slide 17

Slide 17 text

Your users have multi-part stomachs Friday, March 15, 13

Slide 18

Slide 18 text

Here’s some stuﬀ • Tutorials • High-level overviews • Speciﬁc examples • API references • Topical guides • Downloadable samples • FAQs • In-depth guides • Contributing guides • Extension guides Friday, March 15, 13

Slide 19

Slide 19 text

Friday, March 15, 13

Slide 20

Slide 20 text

Know your audience Friday, March 15, 13

Slide 21

Slide 21 text

New users • Assume nothing • Don’t bury them in details • Give plenty of care and feeding (deﬁnitions, explanations, examples) Friday, March 15, 13

Slide 22

Slide 22 text

Experienced users • Assume a few things • Include plenty of links and cross-references • Give practical examples Friday, March 15, 13

Slide 23

Slide 23 text

Friday, March 15, 13

Slide 24

Slide 24 text

Bonjour Friday, March 15, 13

Slide 25

Slide 25 text

Friday, March 15, 13

Slide 26

Slide 26 text

Friday, March 15, 13

Slide 27

Slide 27 text

Friday, March 15, 13

Slide 28

Slide 28 text

Bradypus variegatus (paresseux à gorge brune) Friday, March 15, 13

Slide 29

Slide 29 text

The worst language (except for all the others) Friday, March 15, 13

Slide 30

Slide 30 text

Eschew sesquipedalian loquaciousness Friday, March 15, 13

Slide 31

Slide 31 text

Friday, March 15, 13

Slide 32

Slide 32 text

Documentation-driven development Friday, March 15, 13

Slide 33

Slide 33 text

You know how it’s supposed to work Friday, March 15, 13

Slide 34

Slide 34 text

“If the implementation is hard to explain, it’s a bad idea.” Friday, March 15, 13

Slide 35

Slide 35 text

“If the implementation is easy to explain, it may be a good idea.” Friday, March 15, 13

Slide 36

Slide 36 text

No docs = no merge Friday, March 15, 13

Slide 37

Slide 37 text

(but don’t go overboard) Friday, March 15, 13

Slide 38

Slide 38 text

Friday, March 15, 13

Slide 39

Slide 39 text

Image credits http://www.ﬂickr.com/photos/kcunning/4375118615/ https://en.wikipedia.org/wiki/File:Bradypus.jpg https://en.wikipedia.org/wiki/File:MC_Drei-Finger-Faultier.jpg https://commons.wikimedia.org/wiki/File:Two_toed_sloth.JPG https://commons.wikimedia.org/wiki/ File:Cambridge_Natural_History_Mammalia_Fig_096.jpg https://commons.wikimedia.org/wiki/File:Soths.jpg http://latimesblogs.latimes.com/unleashed/2010/08/baby-sloths.html https://commons.wikimedia.org/wiki/File:Odd-animals35.jpg https://en.wikipedia.org/wiki/File:Bradypus_Range.png https://commons.wikimedia.org/wiki/File:SLOTH_partial_view.jpg Friday, March 15, 13