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

Writing for what Matters

Avatar for Z Z
September 01, 2015
Technology
0
240

Writing for what Matters

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

Z

September 01, 2015
Tweet

More Decks by Z

See All by Z
Delivering APIs for AI
Avatar for Z zdne
0
250
APIs for AI: Have we failed?
Avatar for Z zdne
0
260
AI-enabled APIs
Avatar for Z zdne
0
130
Autonomous Agents
Avatar for Z zdne
0
130
API Documentation & AI
Avatar for Z zdne
0
160
APIs in N-tier architecture
Avatar for Z zdne
0
490
Autonomous Integration Mesh '21
Avatar for Z zdne
0
160
Autonomous APIs (O’Reilly Software Architecture 2019)
Avatar for Z zdne
1
250
What API: Your Guide to API Styles
Avatar for Z zdne
3
1.2k

Other Decks in Technology

See All in Technology
QAはソフトウェアエンジニアリングを学んで実践するのが大事なの
Avatar for ymty ymty
1
400
Copilot Agentを普段使いしてわかった、バックエンド開発で使えるTips
Avatar for ykagano ykagano
1
1.2k
AWS と定理証明 〜ポリシー言語 Cedar 開発の舞台裏〜 #fp_matsuri / FP Matsuri 2025
Avatar for y_taka_23 ytaka23
9
2.5k
宇宙パトロール ルル子から考える LT設計のコツ
Avatar for モブエンジニア masakiokuda
2
100
Clineを含めたAIエージェントを 大規模組織に導入し、投資対効果を考える / Introducing AI agents into your organization
Avatar for Masato Ishigaki / 石垣雅人 i35_267
1
220
活きてなかったデータを活かしてみた話 / Shirokane Kougyou vol 19
Avatar for Sansan R&D sansan_randd
1
350
「実体」で築く共通認識: 開発現場のコミュニケーション最適化 / Let's Get on the Same Page with Concrete Artifacts: Optimization of Communication in dev teams
Avatar for kazizi kazizi55
0
150
Amplifyとゼロからはじめた AIコーディング 成果と展望
Avatar for k.masachika mkdev10
1
280
Devin(Deep) Wiki/Searchの活用で変わる開発の世界観/devin-wiki-search-impact
Avatar for tomoki10 tomoki10
0
340
Snowflake Intelligenceで 実現できるノーコードAI活用
Avatar for tak takumimukaiyama
1
250
ObsidianをMCP連携させてみる
Avatar for ttnyt8701 ttnyt8701
2
130
DroidKnights 2025 - Jetpack XR 살펴보기: XR 개발은 어떻게 이루어지는가?
Avatar for Quokkaman heesung6701
1
120

Featured

See All Featured
Documentation Writing (for coders)
Avatar for Carmen Chung carmenintech
71
4.9k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
Avatar for Tammy Everts tammyeverts
52
2.8k
What's in a price? How to price your products and services
Avatar for Michael Herold michaelherold
245
12k
How To Stay Up To Date on Web Technology
Avatar for Chris Coyier chriscoyier
790
250k
The Language of Interfaces
Avatar for Des Traynor destraynor
158
25k
Understanding Cognitive Biases in Performance Measurement
Avatar for Philip Tellis bluesmoon
29
1.8k
Site-Speed That Sticks
Avatar for Harry Roberts csswizardry
10
640
The Cult of Friendly URLs
Avatar for Andy Hume andyhume
79
6.4k
Faster Mobile Websites
Avatar for Dean Hume deanohume
307
31k
Building a Modern Day 
E-commerce SEO Strategy
Avatar for Aleyda Solis aleyda
41
7.3k
YesSQL, Process and Tooling at Scale
Avatar for Rocio Delgado rocio
172
14k
I Don’t Have Time: Getting Over the Fear to Launch Your Podcast
Avatar for Joe Casabona jcasabona
32
2.3k

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