Link
Embed
Share
Beginning
This slide
Copy link URL
Copy link URL
Copy iframe embed code
Copy iframe embed code
Copy javascript embed code
Copy javascript embed code
Share
Tweet
Share
Tweet
Slide 1
Slide 1 text
Eric Holscher eric@ericholscher.com PDX Python August 13, 2013 Writing docs A beginners guide to writing documentation
Slide 2
Slide 2 text
What you should do • Stop me if anything is unclear • Ask questions
Slide 3
Slide 3 text
About me • Write the Docs • Read the Docs
Slide 4
Slide 4 text
What we’ll cover • Why write docs • What technology • What to write
Slide 5
Slide 5 text
Why Write Docs
Slide 6
Slide 6 text
You will be using your code in 6 months
Slide 7
Slide 7 text
You want people to use your code
Slide 8
Slide 8 text
You want people to help out
Slide 9
Slide 9 text
It makes your code better
Slide 10
Slide 10 text
You want a (better) community
Slide 11
Slide 11 text
You want to be a better writer
Slide 12
Slide 12 text
What Technology
Slide 13
Slide 13 text
Simple is best
Slide 14
Slide 14 text
Plain Text
Slide 15
Slide 15 text
Resources --------- * Online documentation: http://docs.writethedocs.org/ * Conference: http://conf.writethedocs.org/ Basic Example
Slide 16
Slide 16 text
Basic Example
Slide 17
Slide 17 text
Version Controlled
Slide 18
Slide 18 text
Canonical
Slide 19
Slide 19 text
README.md
Slide 20
Slide 20 text
markdowntutorial.com
Slide 21
Slide 21 text
Moving beyond a single file
Slide 22
Slide 22 text
docs/ with files
Slide 23
Slide 23 text
Sphinx See: http://write-the-docs.rtfd.org/sphinx
Slide 24
Slide 24 text
What to write See: write-the-docs.rtfd.org/oss
Slide 25
Slide 25 text
Who are you writing for?
Slide 26
Slide 26 text
What problem your project solves
Slide 27
Slide 27 text
Small code example
Slide 28
Slide 28 text
Major Features
Slide 29
Slide 29 text
Installation Instructions
Slide 30
Slide 30 text
Tutorial
Slide 31
Slide 31 text
Links to code and issues
Slide 32
Slide 32 text
Any other way to get support
Slide 33
Slide 33 text
A license! Reference: http://choosealicense.com/
Slide 34
Slide 34 text
Changelog
Slide 35
Slide 35 text
Cookbook*
Slide 36
Slide 36 text
Community Information*
Slide 37
Slide 37 text
Design Document*
Slide 38
Slide 38 text
Contributor information*
Slide 39
Slide 39 text
Conclusion • Why write docs • What technology • What to write
Slide 40
Slide 40 text
Resources • http://producingoss.com/en/getting- started.html • http://docs.writethedocs.org/ • http://jacobian.org/writing/great- documentation/
Slide 41
Slide 41 text
Interested? • Thinking about starting a doc meetup • groups.google.com/group/write-the-docs
Slide 42
Slide 42 text
This is a living document • It will be edited and live on • Other people can give this talk • Create an intermediate & advanced talk
Slide 43
Slide 43 text
Questions & Feedback • Here and now • eric@ericholscher.com • @ericholscher