Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Writing for what Matters

Sponsored · Your Podcast. Everywhere. Effortlessly. Share. Educate. Inspire. Entertain. You do you. We'll handle the rest. →
Avatar for Z Z
September 01, 2015
Technology
260
0

Writing for what Matters

Talk I gave at the Write the docs conference on August 1st 2015

Avatar for Z

Z

September 01, 2015

More Decks by Z

See All by Z
Agentic Commerce - arcpay.ai
Avatar for Z zdne
1
87
APIs at the Verge of AI
Avatar for Z zdne
0
230
Delivering APIs for AI
Avatar for Z zdne
0
330
APIs for AI: Have we failed?
Avatar for Z zdne
0
350
AI-enabled APIs
Avatar for Z zdne
0
160
Autonomous Agents
Avatar for Z zdne
0
190
API Documentation & AI
Avatar for Z zdne
0
220
APIs in N-tier architecture
Avatar for Z zdne
0
590
Autonomous Integration Mesh '21
Avatar for Z zdne
0
230

Other Decks in Technology

See All in Technology
Claude Code で使える DuckDB Skills を試してみた / DuckDB Skills and Claude Code
Avatar for MasahiroKawahara masahirokawahara
1
880
freeeで運用しているAIQAについて
Avatar for tonchan qatonchan
1
650
最新技術を"今は選ばない"という技術選定
Avatar for Tech Leverages leveragestech
PRO
0
250
業務に残された「良くない型」で考える「TypeScriptの難しさ」
Avatar for Saji sajikix
2
530
可視化から活用へ — Mesh化・Segmentation・アライメントの研究動向
Avatar for GPU UNITE gpuunite_official
0
230
CARTA HOLDINGS エンジニア向け 採用ピッチ資料 / CARTA-GUIDE-for-Engineers
Avatar for CARTA Engineering carta_engineering
0
47k
Loadbalancing exporter internals
Avatar for ymotongpoo ymotongpoo
1
110
PdM・Eng・QAで進めるAI駆動開発の現在地/aidd-with-pdm-eng-qa
Avatar for butatamasoba / Shota Kusaba / 草場翔太 shota_kusaba
0
260
全社統制を維持しながら現場負担をどう減らすか〜プラットフォームチームとセキュリティチームで進めたSecurity Hub活用によるAWS統制の見直し〜/secjaws-security-hub-custom-insights
Avatar for みずほリサーチ&テクノロジーズ株式会社 先端技術研究部 mhrtech
1
600
障害対応のRunbookは作った、でも本当に動くの？ AWS FIS で EKS の AZ 障害を再現してみた
Avatar for Hiroki Takatsuka tk3fftk
0
110
AIのために、AIを使った、Effect-TSからの脱却 〜テストを活用した安全なリファクタリングの進め方〜
Avatar for 株式会社ビットキー / Bitkey Inc. bitkey
PRO
0
120
M&Aで増え続けるプロダクトに少数QAはどう立ち向かうか─GENDAが挑む、全員で取り組む品質標準化戦略 / GENDA Tech Talk #4
Avatar for GENDA genda
0
200

Featured

See All Featured
Making Projects Easy
Avatar for Brett Harned brettharned
120
6.6k
Site-Speed That Sticks
Avatar for Harry Roberts csswizardry
13
1.2k
AI Search:
Where Are We & What Can We Do About It?
Avatar for Aleyda Solis aleyda
0
7.5k
What’s in a name? Adding method to the madness
Avatar for The Alliance productmarketing
PRO
24
4k
The Curse of the Amulet
Avatar for Matthew Lei leimatthew05
1
12k
The MySQL Ecosystem @ GitHub 2015
Avatar for Sam Lambert samlambert
251
13k
Optimizing for Happiness
Avatar for Tom Preston-Werner mojombo
378
71k
The Invisible Side of Design
Avatar for Vitaly Friedman smashingmag
302
52k
Lessons Learnt from Crawling 1000+ Websites
Avatar for Charles Meaden charlesmeaden
PRO
1
1.2k
The Language of Interfaces
Avatar for Des Traynor destraynor
162
26k
How People are Using Generative and Agentic AI to Supercharge Their Products, Projects, Services and Value Streams Today
Avatar for Helen Beal helenjbeal
1
180
Why Your Marketing Sucks and What You Can Do About It - Sophie Logan
Avatar for Sophie Logan marketingsoph
0
140

Transcript

  1. WRITING FOR WHAT MATTERS Z (@zdne) – Apiary.io

  2. Apiary.io

  3. " # % backend developer stake holder client architect writer

  4. SYSTEMS & APIs

  5. OVER 170 000 API DOCUMENTATIONS IN APIARY

  6. WHAT IS DOCUMENTATION?

  7. MARKETING TOOL DRIVING ADOPTION

  8. MOVE FAST AND BREAK THINGS WORLD

  9. THAT’S WHY WE HAVE SO MANY BROKEN THINGS

  10. MIND SHIFT

  11. DOCUMENTATION IS THINKING TOOL

  12. WHY IS NOT DOCUMENTATION TODAY A THINKING TOOL?

  13. OBFUSCATING WHAT MATTERS

  14. 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

  15. LET’S LOOK AT GITHUB EXAMPLE

  16. HOW TO DOCUMENT SYSTEM

  17. DOCUMENT WHAT NOT HOW

  18. DOCUMENT YOUR DATA

  19. DOCUMENT WHAT YOU CAN DO WITH THE DATA

  20. CONTROLLED VOCABULARIES

  21. DESCRIBE YOUR DOMAIN SEMANTICS

  22. CLEAR THINKING GOOD DESIGN

  23. LONGEVITY SCALEABILITY

  24. MACHINE INTEROPERABILITY

  25. “Perhaps there are thoughts we cannot think” – Richard Hamming

  26. MEDIUM FOR THINKING UNTHINKABLE Bret Victor’s

  27. THANK YOU

  28. None

  29. REFERENCE • http://apiary.io • http://goodapi.design • https://vimeo.com/67076984 • https://vimeo.com/71278954 •

    https://channel9.msdn.com/Events/Build/ 2014/3-642