Documentation Journey

Eric Holscher
PDX Node Nov ‘13
 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
 What this talk isn’t

• Telling you how to write docs

• User/Product documentation
 Disclaimer

• I don’t know a lot about Node

 Who am I

• Maintainer of Read the Docs

• Co-Organizer of Write the Docs
Why Write Docs
You will be using your code
in 6 months
You want people to use your
code
You want people to help out
It makes your code better
You want a (better)
community
You want to be a better
writer
Documentation as
Empathy
 outreach

• We want more people to code

• How do I become a programmer?
• Having good documentation allows
people to learn how to program
 Internationalization

• Documentation is much more

accessible for non-native speakers

• Text is most easily translated into other

languages
 Other Audiences

• Each tool is unique

• People want to use your code, so make
it easy for them, whoever they are.
Good Documentation
Types of Documentation

• Tutorials
• Overviews and Topical Guides
• Reference Material
 Tutorials

• Be quick
• Be easy (but not too easy)
• Give a “feel” for your project
 Tutorials

• Great for people who are new to your

project

• Should aim to delight or scare

 Topical Guides

• High level concepts

• Vertical component
• Comprehensive
 Topical Guides

• Great for people who don’t know your

project space well

• Give you the “why”

• The “meat” of your docs
 Reference

• Provide lists of classes and modules

• Organize by hand, generate to keep up
to date
 Reference

• Great for users who already use your

so!ware

• Give you the “how”

 Official

• Good documentation comes from the

project

• Must be constantly updated with code

changes

• Put process in place

If you only have reference
docs, your docs are broken
Current Tools
 README’s

• Great for small projects

• Provide a very specific thing
• Basically a “getting started” doc
 Blog Posts

• Quickly goes out of date

• Stack Overflow solves this problem
better

• Good for Topical Guides

 Wiki’s

• No ownership
• Lower quality based on “someone will
fix it later”
 Books

• Free projects should have free

documentation

• Books are effectively always out of date

 Reference

• Generally provided by automated tools

• http://jsdoc.info/
 State of the Art

• Folder Full of Markdown

• Served on GitHub
• “Website”
Missing bits
 Missing Bits

• Overview of ecosystem/project
• Central Repository for Prose
Documentation

• Standard Tools
 Standard Tooling

• Need a common format

• Where you go a!er a folder full of
markdown

• Not “build a custom website”

Documentation Focused

• Not a website builder

• Needs primitives specific to
documentation
 Tooling Benefits

• Search
• Discovery
• Design
• Interoperability
• Platform (API)
 Easy and Obvious

• New users need an easy way to get

started

• There needs to be an obvious path

towards a good solution
Path Forward
 Community

• Docs are a community problem

• You need to expect them and complain
if they don’t exist
 Young

• You can help shape what the world

looks like

• Derived projects will follow your lead

 Conclusion

• Good documentation is hard work

• Documentation acts as outreach
• Work to improve tools, to make writing
documentation easier
 Reference Links

• jacobian.org/writing/great-
documentation/

• docs.writethedocs.org/en/latest/
writing/beginners-guide-to-docs/
 Thanks

• @ericholscher
• eric@ericholscher.com
• Questions?