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
350
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
510
Other Decks in Technology
See All in Technology
5分でカオスエンジニアリングを分かった気になろう
pandayumi
0
250
プラットフォーム転換期におけるGitHub Copilot活用〜Coding agentがそれを加速するか〜 / Leveraging GitHub Copilot During Platform Transition Periods
aeonpeople
1
210
職種の壁を溶かして開発サイクルを高速に回す~情報透明性と職種越境から考えるAIフレンドリーな職種間連携~
daitasu
0
170
バイブスに「型」を!Kent Beckに学ぶ、AI時代のテスト駆動開発
amixedcolor
2
580
サラリーマンの小遣いで作るtoCサービス - Cloudflare Workersでスケールする開発戦略
shinaps
2
470
Modern Linux
oracle4engineer
PRO
0
150
AI時代を生き抜くエンジニアキャリアの築き方 (AI-Native 時代、エンジニアという道は 「最大の挑戦の場」となる) / Building an Engineering Career to Thrive in the Age of AI (In the AI-Native Era, the Path of Engineering Becomes the Ultimate Arena of Challenge)
jeongjaesoon
0
210
なぜテストマネージャの視点が 必要なのか? 〜 一歩先へ進むために 〜
moritamasami
0
230
roppongirb_20250911
igaiga
1
240
TS-S205_昨年対比2倍以上の機能追加を実現するデータ基盤プロジェクトでのAI活用について
kaz3284
1
210
機械学習を扱うプラットフォーム開発と運用事例
lycorptech_jp
PRO
0
560
フルカイテン株式会社 エンジニア向け採用資料
fullkaiten
0
8.8k
Featured
See All Featured
Imperfection Machines: The Place of Print at Facebook
scottboms
268
13k
Typedesign – Prime Four
hannesfritz
42
2.8k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.9k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
53
2.9k
Product Roadmaps are Hard
iamctodd
PRO
54
11k
The Psychology of Web Performance [Beyond Tellerrand 2023]
tammyeverts
49
3k
The World Runs on Bad Software
bkeepers
PRO
70
11k
Making the Leap to Tech Lead
cromwellryan
135
9.5k
Agile that works and the tools we love
rasmusluckow
330
21k
Build The Right Thing And Hit Your Dates
maggiecrowley
37
2.9k
Fireside Chat
paigeccino
39
3.6k
A designer walks into a library…
pauljervisheath
207
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?