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
200
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
AI-enabled APIs
zdne
0
77
Autonomous Agents
zdne
0
50
API Documentation & AI
zdne
0
110
APIs in N-tier architecture
zdne
0
310
Autonomous Integration Mesh '21
zdne
0
110
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
220
What API: Your Guide to API Styles
zdne
3
1.1k
Consumer APIs Must be Product-Driven
zdne
0
430
Autonomous APIs (Paris 2018)
zdne
1
670
Other Decks in Technology
See All in Technology
ゼロから始めるVue.jsコミュニティ貢献 / first-vuejs-community-contribution-link-and-motivation
lmi
1
130
地理空間データ可視化・解析・活用ソリューション Pacific Spatial Solutions (PSS)
pacificspatialsolutions
0
280
Python と Snowflake はズッ友だょ!~ Snowflake の Python 関連機能をふりかえる ~
__allllllllez__
1
120
データベース02: データベースの概念
trycycle
0
160
エンジニアのキャリアをちょっと楽しくする3本の軸/Three Pillars to Make an Engineer's Career More Enjoyable
kwappa
0
2.7k
On Your Data を超えていく!
hirotomotaguchi
2
690
IaCジェネレーターとBedrockで詳細設計書を生成してみた
tsukasa_ishimaru
1
210
非同期推論システムによるコスト削減と信頼性向上
koki_nishihara
0
260
競技としてのKaggle、役に立つKaggle
yu4u
3
1.5k
今年のRubyKaigiはProfiler Year🤘
osyoyu
0
110
Kernel MemoryでAzure OpenAI Serviceとお手軽データソース連携
mitsuzono
1
250
ChatGPT for IT Service Management (IT Pro)
dahatake
7
1.6k
Featured
See All Featured
Distributed Sagas: A Protocol for Coordinating Microservices
caitiem20
322
20k
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
274
13k
Fight the Zombie Pattern Library - RWD Summit 2016
marcelosomers
227
16k
GitHub's CSS Performance
jonrohan
1025
450k
How STYLIGHT went responsive
nonsquared
92
4.8k
Code Reviewing Like a Champion
maltzj
514
39k
個人開発の失敗を避けるイケてる考え方 / tips for indie hackers
panda_program
60
14k
What's new in Ruby 2.0
geeforr
337
31k
BBQ
matthewcrist
80
8.8k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
125
32k
Understanding Cognitive Biases in Performance Measurement
bluesmoon
7
1k
Atom: Resistance is Futile
akmur
259
25k
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