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
87
Delivering APIs for AI
zdne
0
260
APIs for AI: Have we failed?
zdne
0
270
AI-enabled APIs
zdne
0
130
Autonomous Agents
zdne
0
130
API Documentation & AI
zdne
0
160
APIs in N-tier architecture
zdne
0
500
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
Copilot coding agentにベットしたいCTOが開発組織で取り組んだこと / GitHub Copilot coding agent in Team
tnir
0
150
freeeのアクセシビリティの現在地 / freee's Current Position on Accessibility
ymrl
2
280
How to Quickly Call American Airlines®️ U.S. Customer Care : Full Guide
flyaahelpguide
0
240
AIの全社活用を推進するための安全なレールを敷いた話
shoheimitani
2
640
american airlines®️ USA Contact Numbers: Complete 2025 Support Guide
supportflight
1
120
マーケットプレイス版Oracle WebCenter Content For OCI
oracle4engineer
PRO
3
990
TLSから見るSREの未来
atpons
2
240
大量配信システムにおけるSLOの実践:「見えない」信頼性をSLOで可視化
plaidtech
PRO
0
290
United airlines®️ USA Contact Numbers: Complete 2025 Support Guide
unitedflyhelp
0
340
ロールが細分化された組織でSREは何をするか?
tgidgd
1
200
VGGT: Visual Geometry Grounded Transformer
peisuke
1
620
20250708オープンエンドな探索と知識発見
sakana_ai
PRO
4
860
Featured
See All Featured
[Rails World 2023 - Day 1 Closing Keynote] - The Magic of Rails
eileencodes
35
2.4k
Unsuck your backbone
ammeep
671
58k
KATA
mclloyd
30
14k
BBQ
matthewcrist
89
9.7k
Bootstrapping a Software Product
garrettdimon
PRO
307
110k
How to Think Like a Performance Engineer
csswizardry
25
1.7k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3.3k
Designing for Performance
lara
610
69k
Fireside Chat
paigeccino
37
3.5k
Agile that works and the tools we love
rasmusluckow
329
21k
The World Runs on Bad Software
bkeepers
PRO
69
11k
[RailsConf 2023] Rails as a piece of cake
palkan
55
5.7k
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