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
250
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
150
Delivering APIs for AI
zdne
0
270
APIs for AI: Have we failed?
zdne
0
290
AI-enabled APIs
zdne
0
140
Autonomous Agents
zdne
0
150
API Documentation & AI
zdne
0
180
APIs in N-tier architecture
zdne
0
520
Autonomous Integration Mesh '21
zdne
0
170
Autonomous APIs (O’Reilly Software Architecture 2019)
zdne
1
270
Other Decks in Technology
See All in Technology
AI時代の開発を加速する組織づくり - ブログでは書けなかったリアル
hiro8ma
1
300
Okta Identity Governanceで実現する最小権限の原則 / Implementing the Principle of Least Privilege with Okta Identity Governance
tatsumin39
0
170
AI時代、“平均値”ではいられない
uhyo
8
2.5k
ソースを読むプロセスの例
sat
PRO
15
9.9k
Wasmの気になる最新情報
askua
0
190
GraphRAG グラフDBを使ったLLM生成(自作漫画DBを用いた具体例を用いて)
seaturt1e
1
130
From Natural Language to K8s Operations: The MCP Architecture and Practice of kubectl-ai
appleboy
0
180
デザインとエンジニアリングの架け橋を目指す OPTiMのデザインシステム「nucleus」の軌跡と広げ方
optim
0
100
オブザーバビリティが育むシステム理解と好奇心
maruloop
1
820
SQLAlchemy の select(User).where(User.id =="123") を理解してみる/sqlalchemy deep dive
3l4l5
3
330
物体検出モデルでシイタケの収穫時期を自動判定してみた。 #devio2025
lamaglama39
0
280
OSSで50の競合と戦うためにやったこと
yamadashy
3
970
Featured
See All Featured
Bash Introduction
62gerente
615
210k
Intergalactic Javascript Robots from Outer Space
tanoku
272
27k
RailsConf 2023
tenderlove
30
1.3k
Chrome DevTools: State of the Union 2024 - Debugging React & Beyond
addyosmani
9
930
Gamification - CAS2011
davidbonilla
81
5.5k
Designing for humans not robots
tammielis
254
26k
Producing Creativity
orderedlist
PRO
347
40k
Reflections from 52 weeks, 52 projects
jeffersonlam
353
21k
How to Ace a Technical Interview
jacobian
280
24k
The Web Performance Landscape in 2024 [PerfNow 2024]
tammyeverts
10
890
Context Engineering - Making Every Token Count
addyosmani
8
300
The MySQL Ecosystem @ GitHub 2015
samlambert
251
13k
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