Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
Documentation Journey
Search
ericholscher
November 08, 2013
Technology
1
120
Documentation Journey
A talk about Documentation I gave a PDXNode in November 2013
ericholscher
November 08, 2013
Tweet
Share
More Decks by ericholscher
See All by ericholscher
Introduction to Django Channels - ConFoo Vancouver 2016
ericholscher
0
230
Understanding Documentation Systems - ConFoo Vancouver 2016
ericholscher
0
290
Python Documentation: Past, Present, & Future
ericholscher
3
340
Understanding Documentation Systems
ericholscher
1
280
Documentation as Empathy
ericholscher
1
250
Introduction to Sphinx & Read the Docs Djangocon 2015
ericholscher
0
180
Announcing Read the Docs for Business
ericholscher
1
230
Write the Docs NA 2014 Introduction
ericholscher
0
160
Introduction to Sphinx & Read the Docs
ericholscher
3
500
Other Decks in Technology
See All in Technology
Claude Codeが働くAI中心の業務システム構築の挑戦―AIエージェント中心の働き方を目指して
os1ma
9
1.6k
人に寄り添うAIエージェントとアーキテクチャ #BetAIDay
layerx
PRO
8
2k
LLMをツールからプラットフォームへ〜Ai Workforceの戦略〜 #BetAIDay
layerx
PRO
1
900
o11yツールを乗り換えた話
tak0x00
2
480
データ基盤の管理者からGoogle Cloud全体の管理者になっていた話
zozotech
PRO
0
390
SRE新規立ち上げ! Hubbleインフラのこれまでと展望
katsuya0515
0
170
Claude CodeでKiroの仕様駆動開発を実現させるには...
gotalab555
3
930
LLMで構造化出力の成功率をグンと上げる方法
keisuketakiguchi
0
570
マルチモーダル基盤モデルに基づく動画と音の解析技術
lycorptech_jp
PRO
5
560
AI時代の経営、Bet AI Vision #BetAIDay
layerx
PRO
1
1.8k
UDDのススメ - 拡張版 -
maguroalternative
1
310
データモデリング通り #2オンライン勉強会 ~方法論の話をしよう~
datayokocho
0
120
Featured
See All Featured
Designing Experiences People Love
moore
142
24k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
46
7.5k
Connecting the Dots Between Site Speed, User Experience & Your Business [WebExpo 2025]
tammyeverts
8
430
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
126
53k
KATA
mclloyd
32
14k
Build The Right Thing And Hit Your Dates
maggiecrowley
37
2.8k
Balancing Empowerment & Direction
lara
1
530
4 Signs Your Business is Dying
shpigford
184
22k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
194
16k
Measuring & Analyzing Core Web Vitals
bluesmoon
8
540
Agile that works and the tools we love
rasmusluckow
329
21k
VelocityConf: Rendering Performance Case Studies
addyosmani
332
24k
Transcript
Eric Holscher PDX Node Nov ‘13 Documentation Journey
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?