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
84
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
DBのスキルで生き残る技術 - AI時代におけるテーブル設計の勘所
soudai
PRO
54
22k
マルチプロダクト環境におけるSREの役割 / SRE NEXT 2025 lunch session
sugamasao
1
220
AI エージェントと考え直すデータ基盤
na0
17
6.8k
スタートアップに選択肢を 〜生成AIを活用したセカンダリー事業への挑戦〜
nstock
0
270
AWS CDK 開発を成功に導くトラブルシューティングガイド
wandora58
3
140
ビジネス職が分析も担う事業部制組織でのデータ活用の仕組みづくり / Enabling Data Analytics in Business-Led Divisional Organizations
zaimy
1
290
QuickSight SPICE の効果的な運用戦略~S3 + Athena 構成での実践ノウハウ~/quicksight-spice-s3-athena-best-practices
emiki
0
240
全部AI、全員Cursor、ドキュメント駆動開発 〜DevinやGeminiも添えて〜
rinchsan
2
500
助けて! XからWaylandに移行しないと新しいGNOMEが使えなくなっちゃう 2025-07-12
nobutomurata
2
130
American airlines ®️ USA Contact Numbers: Complete 2025 Support Guide
airhelpsupport
0
390
shake-upを科学する
rsakata
7
900
United Airlines Customer Service– Call 1-833-341-3142 Now!
airhelp
0
170
Featured
See All Featured
Exploring the Power of Turbo Streams & Action Cable | RailsConf2023
kevinliebholz
34
5.9k
Gamification - CAS2011
davidbonilla
81
5.4k
Thoughts on Productivity
jonyablonski
69
4.7k
Building an army of robots
kneath
306
45k
Why Our Code Smells
bkeepers
PRO
336
57k
How to Think Like a Performance Engineer
csswizardry
25
1.7k
BBQ
matthewcrist
89
9.7k
The Success of Rails: Ensuring Growth for the Next 100 Years
eileencodes
45
7.5k
Bash Introduction
62gerente
613
210k
Building Adaptive Systems
keathley
43
2.7k
Rebuilding a faster, lazier Slack
samanthasiow
83
9.1k
Optimizing for Happiness
mojombo
379
70k
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