Write the Docs by James Bennett

The greatest piece of software in the world is useless without great documentation, but unfortunately most of us just don't write great docs. This can be fixed, though. Documentation doesn't need to be an afterthought, and doesn't have to be bad, and you, too, can learn how to write good docs and make that an integrated part of your development process.

Transcript

1. Write the Docs James Bennett · PyCon US 2013 Santa Clara, California Friday, March 15, 13
2. Hi. Friday, March 15, 13
3. Friday, March 15, 13
4. Friday, March 15, 13
5. Friday, March 15, 13
6. Bradypus variegatus (brown-throated three-toed sloth) Friday, March 15, 13
7. 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
8. Software users Friday, March 15, 13
9. Happy sloth (its name is Herman) Friday, March 15, 13
10. Happy users • Stay with you • Promote your software • Contribute to your software Friday, March 15, 13
11. 0 25 50 75 100 Happy users Bad documentation Great documentation Friday, March 15, 13
12. You need great documentation Friday, March 15, 13
13. Make this happen Friday, March 15, 13
14. The one thing Friday, March 15, 13
15. Friday, March 15, 13
16. Remember the second sloth fact? Friday, March 15, 13
17. Your users have multi-part stomachs Friday, March 15, 13
18. Here’s some stuff • Tutorials • High-level overviews • Specific examples • API references • Topical guides • Downloadable samples • FAQs • In-depth guides • Contributing guides • Extension guides Friday, March 15, 13
19. Friday, March 15, 13
20. Know your audience Friday, March 15, 13
21. New users • Assume nothing • Don’t bury them in details • Give plenty of care and feeding (definitions, explanations, examples) Friday, March 15, 13
22. Experienced users • Assume a few things • Include plenty of links and cross-references • Give practical examples Friday, March 15, 13
23. Friday, March 15, 13
24. Bonjour Friday, March 15, 13
25. Friday, March 15, 13
26. Friday, March 15, 13
27. Friday, March 15, 13
28. Bradypus variegatus (paresseux à gorge brune) Friday, March 15, 13
29. The worst language (except for all the others) Friday, March 15, 13
30. Eschew sesquipedalian loquaciousness Friday, March 15, 13
31. Friday, March 15, 13
32. Documentation-driven development Friday, March 15, 13
33. You know how it’s supposed to work Friday, March 15, 13
34. “If the implementation is hard to explain, it’s a bad idea.” Friday, March 15, 13
35. “If the implementation is easy to explain, it may be a good idea.” Friday, March 15, 13
36. No docs = no merge Friday, March 15, 13
37. (but don’t go overboard) Friday, March 15, 13
38. Friday, March 15, 13
39. Image credits http://www.flickr.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