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
150
Delivering APIs for AI
zdne
0
270
APIs for AI: Have we failed?
zdne
0
290
AI-enabled APIs
zdne
0
140
Autonomous Agents
zdne
0
140
API Documentation & AI
zdne
0
180
APIs in N-tier architecture
zdne
0
510
Autonomous Integration Mesh '21
zdne
0
170
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
270
Other Decks in Technology
See All in Technology
E2Eテスト設計_自動化のリアル___Playwrightでの実践とMCPの試み__AIによるテスト観点作成_.pdf
findy_eventslides
1
490
SoccerNet GSRの紹介と技術応用:選手視点映像を提供するサッカー作戦盤ツール
mixi_engineers
PRO
1
190
業務自動化プラットフォーム Google Agentspace に入門してみる #devio2025
maroon1st
0
200
Oracle Cloud Infrastructure:2025年9月度サービス・アップデート
oracle4engineer
PRO
0
470
空間を設計する力を考える / 20251004 Naoki Takahashi
shift_evolve
PRO
3
410
生成AIとM5Stack / M5 Japan Tour 2025 Autumn 東京
you
PRO
0
230
AWS Top Engineer、浮いてませんか? / As an AWS Top Engineer, Are You Out of Place?
yuj1osm
2
120
「Verify with Wallet API」を アプリに導入するために
hinakko
1
250
Azure SynapseからAzure Databricksへ 移行してわかった新時代のコスト問題!?
databricksjapan
0
150
社内お問い合わせBotの仕組みと学び
nish01
0
460
Why React!?? Next.jsそしてReactを改めてイチから選ぶ
ypresto
10
4.5k
『OCI で学ぶクラウドネイティブ 実践 × 理論ガイド』 書籍概要
oracle4engineer
PRO
2
130
Featured
See All Featured
The Art of Delivering Value - GDevCon NA Keynote
reverentgeek
15
1.7k
Documentation Writing (for coders)
carmenintech
75
5k
The Cult of Friendly URLs
andyhume
79
6.6k
Put a Button on it: Removing Barriers to Going Fast.
kastner
60
4k
Navigating Team Friction
lara
189
15k
The MySQL Ecosystem @ GitHub 2015
samlambert
251
13k
The Art of Programming - Codeland 2020
erikaheidi
56
14k
Fireside Chat
paigeccino
40
3.7k
YesSQL, Process and Tooling at Scale
rocio
173
14k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
29
2.6k
The Power of CSS Pseudo Elements
geoffreycrofte
79
6k
Git: the NoSQL Database
bkeepers
PRO
431
66k
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