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

Writing for what Matters

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
September 01, 2015
Technology
0
160

Writing for what Matters

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

Cb2527e0c321fc1eb6753c06f45da93c?s=128

Z

September 01, 2015
Tweet

More Decks by Z

See All by Z
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
1
91
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
3
850
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
0
220
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
1
560
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
7
150k
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
2
500
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
1
390
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
2
790
Cb2527e0c321fc1eb6753c06f45da93c?s=48 zdne
1
690

Other Decks in Technology

See All in Technology
5d9c07f0c2044b1407a84d88362bc84d?s=48 estie
0
140
7cd783377515bdf8207062840b7b2f4e?s=48 soracom
PRO
0
180
15c2fcbb0358a6c4910fb043e2b1f71e?s=48 yuitosato
1
470
A73e8918471bd7e3065d129e2ed75e98?s=48 ystk_hara
0
430
A35557d139d8d53246763a01ec847a3f?s=48 kichiemon
2
120
8d6c54ebb889a5fe3f77b763d563fd9f?s=48 serinuntius
0
370
3ac512f1cbab89f8671ff4718f23d150?s=48 takewell
0
250
18f1e3993e9ead63e7a0f70d9eb996bb?s=48 wkm2
0
140
D2f212ce418f3daa29c23914c9b6892b?s=48 kenmaz
1
160
Cd931bc05e7cee46b9a950a63e47ba4c?s=48 you
0
130
63bf22db8ab8da3851da34d2e0cb0c69?s=48 imairi
6
580
79dcb04101764d7bf66f898dd446838e?s=48 tsukubachallenge
0
250

Featured

See All Featured
170b760e0147792d0140e59ec78e9893?s=48 eitanlees
118
11k
1f74b13f1e5c6c69cb5d7fbaabb1e2cb?s=48 sferik
612
56k
2bb923c57a1fdc3a2eb484bb8d565fd2?s=48 ufuk
60
7.2k
9952dfcd5d338f8a8e7175c8a8f65fb5?s=48 wjessup
342
16k
B83d5b590577969ee79a5ad845411a7d?s=48 ammeep
660
54k
Be9caeb9d4ef9944d151af909063ed6e?s=48 samlambert
238
10k
Ef32e0b1ac5082450dc8c1fca3a26b5c?s=48 cherdarchuk
77
270k
Ded01cdab114abe4ec13511e4c25b9bb?s=48 andyhume
67
4.4k
A415db3ac9e9668acbc1fb36eead84ac?s=48 mthomps
44
2.5k
7c8469ee8c9e594c65c59b919626c08d?s=48 scottboms
253
11k
C86443373fbfe92996aa882d0d7a59f8?s=48 imathis
482
150k
245cee81a9c424266e5e401d844ea881?s=48 lara
26
3.4k

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