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
76
Autonomous Agents
zdne
0
45
API Documentation & AI
zdne
0
110
APIs in N-tier architecture
zdne
0
290
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
420
Autonomous APIs (Paris 2018)
zdne
1
660
Other Decks in Technology
See All in Technology
Automate your changelogs! Release Drafter
onenashev
PRO
2
410
最速思考でバクラク品質を! スタートアップのリアルな課題とQAの実践
nakanao
1
450
ChatGPTのLT会-メモソフトにChatGPT入れると結構便利
okada_fuutass
0
160
Command-line interface tool design / PHPerKaigi 2024
k1low
4
1k
GitHub Actions Runner Controller
takesection
0
110
Node-AI のリッチな WEB フロントエンドを支える技術
nenonaninu
2
970
【Cyber-sec+】ログの森で出会ったCloudTrail との奇妙な旅
hssh2_bin
1
230
人工衛星管制システムにおけるCICD / CICD in satellite control systems
iselegant
5
900
【OpenAI本出版記念】npakaによるOpenAI最新技術情報と技術情報キャッチアップ術
npaka
8
1.5k
令和最新版 ソフトウェアエンジニアのためのDJ入門、あるいはDJに学ぶ仕事術 #ya8
stefafafan
1
140
S3成長記録@Storage-JAWS#3
p0n
0
130
スクラムガイドに載っていないスクラムのはじめかた - チームでスクラムをはじめるときに知っておきたい5個のコツ - / How to start Scrum that is not written in the Scrum Guide
takaking22
14
5.3k
Featured
See All Featured
Design by the Numbers
sachag
274
18k
Large-scale JavaScript Application Architecture
addyosmani
501
110k
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
11
1.4k
The Language of Interfaces
destraynor
150
22k
Mobile First: as difficult as doing things right
swwweet
215
8.5k
Agile that works and the tools we love
rasmusluckow
323
20k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
67
38k
Designing Experiences People Love
moore
135
23k
Learning to Love Humans: Emotional Interface Design
aarron
266
39k
JavaScript: Past, Present, and Future - NDC Porto 2020
reverentgeek
39
4.3k
Debugging Ruby Performance
tmm1
68
11k
The Brand Is Dead. Long Live the Brand.
mthomps
48
20k
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