Writing for what Matters

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

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