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

Writing for what Matters

Sponsored · SiteGround - Reliable hosting with speed, security, and support you can count on. →
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
When AI Agents Start Moving Money
Avatar for Z zdne
0
20
Agentic Commerce - arcpay.ai
Avatar for Z zdne
1
110
APIs at the Verge of AI
Avatar for Z zdne
0
240
Delivering APIs for AI
Avatar for Z zdne
0
330
APIs for AI: Have we failed?
Avatar for Z zdne
0
360
AI-enabled APIs
Avatar for Z zdne
0
170
Autonomous Agents
Avatar for Z zdne
0
200
API Documentation & AI
Avatar for Z zdne
0
220
APIs in N-tier architecture
Avatar for Z zdne
0
600

Other Decks in Technology

See All in Technology
CVE-2026-20833_脆弱性対応とAES 化について
Avatar for Jun1214 jukishiya
0
210
「勝手に広まる」人気 AI エージェントを爆速で作ろう！（AWS Summit Japan 2026講演資料）
Avatar for みのるん minorun365
PRO
10
2.6k
デジタル・デザイン：次の50年を描く「進化する青写真」
Avatar for Sayaka Ishizuka y150saya
0
150
徹底討論！ECS vs EKS！
Avatar for 高棹大樹 daitak
3
1.8k
スタートアップにAmazon EKSは早すぎる？ マルチプロダクト戦略を加速する Platform Engineeringの実践 / Is Amazon EKS Too Soon for Startups? Practical Platform Engineering to Accelerate a Multi-Product Strategy
Avatar for elmo elmodev09
1
1.9k
AI-DLCを “そのまま導入しなかった”話 ~組織に合わせてアジャストした 私たちの実践共有~
Avatar for hiroramos hiroramos4
PRO
1
450
IaC コードを資産へ：AWS CDK 社内ライブラリと横断展開 / aws-summit-japan-2026
Avatar for k.goto gotok365
10
1.6k
Why is RC4 still being used?
Avatar for tamaiyutaro tamaiyutaro
0
180
Agile and AI Redmine Japan 2026
Avatar for Kenji Hiranabe hiranabe
4
500
AIペネトレーションテスト・ セキュリティ検証「AgenticSec」紹介資料
Avatar for Sho Nakatani laysakura
2
7.7k
ご挨拶「10周年を迎える共創ラボのこれまでとこれから」
Avatar for AIxIoTビジネス共創ラボ iotcomjpadmin
0
150
「軸足」は 固定しなくていい - 熱量と強みで描く、しなやかなキャリアの形
Avatar for KAKEHASHI kakehashi
PRO
1
290

Featured

See All Featured
Unlocking the hidden potential of vector embeddings in international SEO
Avatar for Frank van Dijk frankvandijk
0
850
First, design no harm
Avatar for Per Axbom axbom
PRO
2
1.2k
Code Review Best Practice
Avatar for Trisha Gee trishagee
74
20k
Agile Leadership in an Agile Organization
Avatar for Dr. Kim W Petersen kimpetersen
PRO
0
170
Building Applications with DynamoDB
Avatar for Matt Wood mza
96
7.1k
Designing for Timeless Needs
Avatar for Cassini Nazir cassininazir
1
260
Mobile First: as difficult as doing things right
Avatar for Swwweet swwweet
225
10k
It's Worth the Effort
Avatar for 3n 3n
188
29k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
Avatar for Dan Newman danielanewman
230
23k
So, you think you're a good person
Avatar for Per Axbom axbom
PRO
2
2.1k
Reflections from 52 weeks, 52 projects
Avatar for Jefferson Lam jeffersonlam
356
21k
Performance Is Good for Brains [We Love Speed 2024]
Avatar for Tammy Everts tammyeverts
12
1.7k

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