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
130
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
なぜスクラムはこうなったのか?歴史が教えてくれたこと/Shall we explore the roots of Scrum
sanogemaru
3
960
RSCの時代にReactとフレームワークの境界を探る
uhyo
9
3k
Nstockの一人目エンジニアが 3年間かけて向き合ってきた セキュリティのこととこれから〜あれから半年〜
yo41sawada
0
200
AIのグローバルトレンド2025 #scrummikawa / global ai trend
kyonmm
PRO
1
240
ChatGPTとPlantUML/Mermaidによるソフトウェア設計
gowhich501
1
120
ZOZOマッチのアーキテクチャと技術構成
zozotech
PRO
3
1.3k
シークレット管理だけじゃない!HashiCorp Vault でデータ暗号化をしよう / Beyond Secret Management! Let's Encrypt Data with HashiCorp Vault
nnstt1
3
220
AWSで始める実践Dagster入門
kitagawaz
0
290
Skrub: machine-learning with dataframes
gaelvaroquaux
0
120
【Grafana Meetup Japan #6】Grafanaをリバプロ配下で動かすときにやること ~ Grafana Liveってなんだ ~
yoshitake945
0
300
LLM翻訳ツールの開発と海外のお客様対応等への社内導入事例
gree_tech
PRO
0
560
AI時代に非連続な成長を実現するエンジニアリング戦略
sansantech
PRO
3
1.1k
Featured
See All Featured
Keith and Marios Guide to Fast Websites
keithpitt
411
22k
Code Review Best Practice
trishagee
70
19k
Put a Button on it: Removing Barriers to Going Fast.
kastner
60
4k
Stop Working from a Prison Cell
hatefulcrawdad
271
21k
Making the Leap to Tech Lead
cromwellryan
135
9.5k
Imperfection Machines: The Place of Print at Facebook
scottboms
268
13k
Why Our Code Smells
bkeepers
PRO
339
57k
Navigating Team Friction
lara
189
15k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
358
30k
Rebuilding a faster, lazier Slack
samanthasiow
83
9.2k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
131
19k
The Web Performance Landscape in 2024 [PerfNow 2024]
tammyeverts
9
800
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