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

Writing for what Matters

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
September 01, 2015

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

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