Thanks to visit codestin.com
Credit goes to www.scribd.com

Scribd
Upload
63 views45 pages

Node Doc Talk PDF

This document discusses the importance of documentation and provides best practices for documentation. It recommends focusing on tutorials, topical guides, and reference material. Good documentation comes directly from a project and must be constantly updated. Current tools like READMEs, blogs, and wikis have limitations. There is a need for standard tooling that is documentation focused and makes writing documentation easier through features like search and an obvious path for getting started. Improving documentation helps projects, users, and the developer community overall.

Uploaded by

Eric Chua
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
63 views45 pages

Node Doc Talk PDF

This document discusses the importance of documentation and provides best practices for documentation. It recommends focusing on tutorials, topical guides, and reference material. Good documentation comes directly from a project and must be constantly updated. Current tools like READMEs, blogs, and wikis have limitations. There is a need for standard tooling that is documentation focused and makes writing documentation easier through features like search and an obvious path for getting started. Improving documentation helps projects, users, and the developer community overall.

Uploaded by

Eric Chua
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 45

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
• [email protected]
• Questions?

You might also like