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
Sponsored
·
Your Podcast. Everywhere. Effortlessly.
Share. Educate. Inspire. Entertain. You do you. We'll handle the rest.
→
Z
September 01, 2015
Technology
0
250
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
Agentic Commerce - arcpay.ai
zdne
1
51
APIs at the Verge of AI
zdne
0
200
Delivering APIs for AI
zdne
0
300
APIs for AI: Have we failed?
zdne
0
310
AI-enabled APIs
zdne
0
140
Autonomous Agents
zdne
0
170
API Documentation & AI
zdne
0
200
APIs in N-tier architecture
zdne
0
540
Autonomous Integration Mesh '21
zdne
0
200
Other Decks in Technology
See All in Technology
20260208_第66回 コンピュータビジョン勉強会
keiichiito1978
0
150
仕様書駆動AI開発の実践: Issue→Skill→PRテンプレで 再現性を作る
knishioka
2
670
OpenShiftでllm-dを動かそう!
jpishikawa
0
110
Kiro IDEのドキュメントを全部読んだので地味だけどちょっと嬉しい機能を紹介する
khmoryz
0
200
モダンUIでフルサーバーレスなAIエージェントをAmplifyとCDKでサクッとデプロイしよう
minorun365
4
210
All About Sansan – for New Global Engineers
sansan33
PRO
1
1.4k
顧客との商談議事録をみんなで読んで顧客解像度を上げよう
shibayu36
0
250
usermode linux without MMU - fosdem2026 kernel devroom
thehajime
0
240
茨城の思い出を振り返る ~CDKのセキュリティを添えて~ / 20260201 Mitsutoshi Matsuo
shift_evolve
PRO
1
320
配列に見る bash と zsh の違い
kazzpapa3
3
160
プロポーザルに込める段取り八分
shoheimitani
1
280
クレジットカード決済基盤を支えるSRE - 厳格な監査とSRE運用の両立 (SRE Kaigi 2026)
capytan
6
2.8k
Featured
See All Featured
Claude Code どこまでも/ Claude Code Everywhere
nwiizo
61
52k
The SEO identity crisis: Don't let AI make you average
varn
0
290
Ten Tips & Tricks for a 🌱 transition
stuffmc
0
69
Context Engineering - Making Every Token Count
addyosmani
9
660
Tell your own story through comics
letsgokoyo
1
810
Fashionably flexible responsive web design (full day workshop)
malarkey
408
66k
Agile Actions for Facilitating Distributed Teams - ADO2019
mkilby
0
110
Intergalactic Javascript Robots from Outer Space
tanoku
273
27k
Testing 201, or: Great Expectations
jmmastey
46
8k
Balancing Empowerment & Direction
lara
5
890
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
128
55k
Agile that works and the tools we love
rasmusluckow
331
21k
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