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
Writing for what Matters
Search
Z
September 01, 2015
Technology
0
240
Writing for what Matters
Talk I gave at the Write the docs conference on August 1st 2015
Z
September 01, 2015
Tweet
Share
More Decks by Z
See All by Z
APIs at the Verge of AI
zdne
0
140
Delivering APIs for AI
zdne
0
270
APIs for AI: Have we failed?
zdne
0
290
AI-enabled APIs
zdne
0
130
Autonomous Agents
zdne
0
140
API Documentation & AI
zdne
0
170
APIs in N-tier architecture
zdne
0
510
Autonomous Integration Mesh '21
zdne
0
170
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
260
Other Decks in Technology
See All in Technology
Snowflake×dbtを用いたテレシーのデータ基盤のこれまでとこれから
sagara
0
120
RSCの時代にReactとフレームワークの境界を探る
uhyo
10
3.5k
dbt開発 with Claude Codeのためのガードレール設計
10xinc
2
1.3k
[ JAWS-UG 東京 CommunityBuilders Night #2 ]SlackとAmazon Q Developerで 運用効率化を模索する
sh_fk2
3
460
💡Ruby 川辺で灯すPicoRubyからの光
bash0c7
0
120
メルカリIBISの紹介
0gm
0
120
初めてAWSを使うときのセキュリティ覚書〜初心者支部編〜
cmusudakeisuke
1
280
KotlinConf 2025_イベントレポート
sony
1
140
会社紹介資料 / Sansan Company Profile
sansan33
PRO
6
380k
新規プロダクトでプロトタイプから正式リリースまでNext.jsで開発したリアル
kawanoriku0
1
200
MagicPod導入から半年、オープンロジQAチームで実際にやったこと
tjoko
0
110
いま注目のAIエージェントを作ってみよう
supermarimobros
0
350
Featured
See All Featured
Thoughts on Productivity
jonyablonski
70
4.8k
Rails Girls Zürich Keynote
gr2m
95
14k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
234
17k
GraphQLの誤解/rethinking-graphql
sonatard
72
11k
YesSQL, Process and Tooling at Scale
rocio
173
14k
VelocityConf: Rendering Performance Case Studies
addyosmani
332
24k
Measuring & Analyzing Core Web Vitals
bluesmoon
9
580
The Straight Up "How To Draw Better" Workshop
denniskardys
236
140k
Reflections from 52 weeks, 52 projects
jeffersonlam
352
21k
Balancing Empowerment & Direction
lara
3
620
Java REST API Framework Comparison - PWX 2021
mraible
33
8.8k
How to Think Like a Performance Engineer
csswizardry
26
1.9k
Transcript
WRITING FOR WHAT MATTERS Z (@zdne) – Apiary.io
Apiary.io
" # % backend developer stake holder client architect writer
SYSTEMS & APIs
OVER 170 000 API DOCUMENTATIONS IN APIARY
WHAT IS DOCUMENTATION?
MARKETING TOOL DRIVING ADOPTION
MOVE FAST AND BREAK THINGS WORLD
THAT’S WHY WE HAVE SO MANY BROKEN THINGS
MIND SHIFT
DOCUMENTATION IS THINKING TOOL
WHY IS NOT DOCUMENTATION TODAY A THINKING TOOL?
OBFUSCATING WHAT MATTERS
DOCUMENTATION ANATOMY • PROTOCOL DETAILS • AUTHENTICATION • PAGINATION •
RATE LIMITING • HOW TO CONTACT LAWYERS • WHAT YOU THINK I WANT TO DO WITH YOUR API • DATA • WHAT CAN BE DONE WITH DATA
LET’S LOOK AT GITHUB EXAMPLE
HOW TO DOCUMENT SYSTEM
DOCUMENT WHAT NOT HOW
DOCUMENT YOUR DATA
DOCUMENT WHAT YOU CAN DO WITH THE DATA
CONTROLLED VOCABULARIES
DESCRIBE YOUR DOMAIN SEMANTICS
CLEAR THINKING GOOD DESIGN
LONGEVITY SCALEABILITY
MACHINE INTEROPERABILITY
“Perhaps there are thoughts we cannot think” – Richard Hamming
MEDIUM FOR THINKING UNTHINKABLE Bret Victor’s
THANK YOU
None
REFERENCE • http://apiary.io • http://goodapi.design • https://vimeo.com/67076984 • https://vimeo.com/71278954 •
https://channel9.msdn.com/Events/Build/ 2014/3-642