Eric Holscher
PDX Node Nov ‘13
Documentation Journey
Slide 2
Slide 2 text
What This Talk Is
• High level overview of how to think
about documentation
• Why documentation matters
• Overview of my thoughts on doing docs
well
• Discussion around Node community
documentation
Slide 3
Slide 3 text
What this talk isn’t
• Telling you how to write docs
• User/Product documentation
Slide 4
Slide 4 text
Disclaimer
• I don’t know a lot about Node
Slide 5
Slide 5 text
Who am I
• Maintainer of Read the Docs
• Co-Organizer of Write the Docs
Slide 6
Slide 6 text
Why Write Docs
Slide 7
Slide 7 text
You will be using your code
in 6 months
Slide 8
Slide 8 text
You want people to use your
code
Slide 9
Slide 9 text
You want people to help out
Slide 10
Slide 10 text
It makes your code better
Slide 11
Slide 11 text
You want a (better)
community
Slide 12
Slide 12 text
You want to be a better
writer
Slide 13
Slide 13 text
Documentation as
Empathy
Slide 14
Slide 14 text
outreach
• We want more people to code
• How do I become a programmer?
• Having good documentation allows
people to learn how to program
Slide 15
Slide 15 text
Internationalization
• Documentation is much more
accessible for non-native speakers
• Text is most easily translated into other
languages
Slide 16
Slide 16 text
Other Audiences
• Each tool is unique
• People want to use your code, so make
it easy for them, whoever they are.
Slide 17
Slide 17 text
Good Documentation
Slide 18
Slide 18 text
Types of Documentation
• Tutorials
• Overviews and Topical Guides
• Reference Material
Slide 19
Slide 19 text
Tutorials
• Be quick
• Be easy (but not too easy)
• Give a “feel” for your project
Slide 20
Slide 20 text
Tutorials
• Great for people who are new to your
project
• Should aim to delight or scare