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
0
250

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
Agentic Commerce - arcpay.ai
Avatar for Z zdne
1
63
APIs at the Verge of AI
Avatar for Z zdne
0
210
Delivering APIs for AI
Avatar for Z zdne
0
300
APIs for AI: Have we failed?
Avatar for Z zdne
0
320
AI-enabled APIs
Avatar for Z zdne
0
150
Autonomous Agents
Avatar for Z zdne
0
170
API Documentation & AI
Avatar for Z zdne
0
200
APIs in N-tier architecture
Avatar for Z zdne
0
550
Autonomous Integration Mesh '21
Avatar for Z zdne
0
200

Other Decks in Technology

See All in Technology
Raspberry Pi AI HAT+ 2 介紹(#49)
Avatar for 台灣樹莓派 piepie_tw
PRO
0
150
Exadata Fleet Update
Avatar for oracle4engineer oracle4engineer
PRO
0
1.3k
Digitization部 紹介資料
Avatar for Sansan, Inc. sansan33
PRO
1
7k
Oracle Base Database Service 技術詳細
Avatar for oracle4engineer oracle4engineer
PRO
15
95k
バクラクにおける Document Understanding の挑戦：書類の「読取」から「意思決定」へ / document-understanding-in-bakuraku-2026
Avatar for Yuya Matsumura yuya4
0
190
【PyCon mini Shizuoka 2026】生成AI時代に画像処理やオーディオ処理のノードエディターを作る理由
Avatar for 高橋かずひと kazuhitotakahashi
0
240
AIエンジニア Devin と歩む、自律型運用プロセスの構築
Avatar for a2-ito a2ito
0
560
Databricksアシスタントが自分で考えて動く時代に! エージェントモード体験もくもく会
Avatar for Takaaki Yayoi taka_aki
0
270
社内ワークショップで終わらせない 業務改善AIエージェント開発
Avatar for LINEヤフーTech (LY Corporation Tech) lycorptech_jp
PRO
1
440
opsmethod第1回_アラート調査の自動化にむけて
Avatar for OKU/YAMATO yamatook
0
330
1 年間の育休から時短勤務で復帰した私が、 AI を駆使して立ち上がりを早めた話
Avatar for LINEヤフーTech (LY Corporation Tech) lycorptech_jp
PRO
0
210
Webアクセシビリティ技術と実装の実際
Avatar for tomokusaba tomokusaba
0
190

Featured

See All Featured
The Director’s Chair: Orchestrating AI for Truly Effective Learning
Avatar for Mike Taylor tmiket
1
110
Game over? The fight for quality and originality in the time of robots
Avatar for Wayne Barker wayneb77
1
130
From π to Pie charts
Avatar for Rasagy Sharma rasagy
0
140
How to Talk to Developers About Accessibility
Avatar for Jason CranfordTeague jct
2
140
Design and Strategy: How to Deal with People Who Don’t "Get" Design
Avatar for Morgane Peng morganepeng
133
19k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
Avatar for Tammy Everts tammyeverts
55
3.3k
Digital Projects Gone Horribly Wrong (And the UX Pros Who Still Save the Day) - Dean Schuster
Avatar for UX Y'all uxyall
0
580
First, design no harm
Avatar for Per Axbom axbom
PRO
2
1.1k
Lessons Learnt from Crawling 1000+ Websites
Avatar for Charles Meaden charlesmeaden
PRO
1
1.1k
Dealing with People You Can't Stand - Big Design 2015
Avatar for Cassini Nazir cassininazir
367
27k
Marketing Yourself as an Engineer | Alaka | Gurzu
Avatar for Gurzu gurzu
0
140
Agile Actions for Facilitating Distributed Teams - ADO2019
Avatar for Mark Kilby mkilby
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