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

Turks, Aliens and Thinking

Cb2527e0c321fc1eb6753c06f45da93c?s=47 Z
September 08, 2016

Turks, Aliens and Thinking

Cb2527e0c321fc1eb6753c06f45da93c?s=128

Z

September 08, 2016
Tweet

Transcript

  1. TURKS, ALIENS and THINKING Z (@zdne) apiary.io

  2. TWO CHALLENGES 1 APIs aren’t the endgame 2 Documentation isn’t

    what you think
  3. PART I APIs AREN’T ENDGAME

  4. THE TURK ~1770~

  5. Wolfgang von Kempelen

  6. None
  7. None
  8. None
  9. ALIENS ~1963~

  10. Joseph Carl Robnett Licklider

  11. COMMUNICATING WITH ALIENS PROBLEM

  12. Memorandum For Members and Affiliates of the Intergalactic Computer Network

    Consider the situation in which several different centers are netted together, each center being highly individualistic and having its own special language and its own special way of doing things. Is it not desirable, or even necessary for all the centers to agree upon some language or, at least, upon some conventions for asking such questions as “What language do you speak?” At this extreme, the problem is essentially the one discussed by science fiction writers: “how do you get communications started among totally uncorrelated 'sapient' beings?.”
  13. INTERGALACTIC COMPUTER NETWORK How would completely unrelated beings communicate?

  14. THEY WOULD HAVE TO FIGURE OUT

  15. PROBE TO BUILD SHARED VOCABULARY

  16. RISE OF TURKS ~1999~

  17. PLANETARY COMPUTER NETWORK How would distributed components communicate?

  18. THEY WOULD HAVE TO FIGURE OUT

  19. OR?

  20. HAVE SOME A PRIORI UNDERSTANDING

  21. SHARED UNDERSTANDING AHEAD OF TIME 1 A component exposes an

    interface
  22. SHARED UNDERSTANDING AHEAD OF TIME 1 A component exposes an

    interface 2 Some humans write a lot of text to document it
  23. SHARED UNDERSTANDING AHEAD OF TIME 1 A component exposes an

    interface 2 Some humans write a lot of text to document it 3 Some other humans read it
  24. SHARED UNDERSTANDING AHEAD OF TIME 1 A component exposes an

    interface 2 Some humans write a lot of text to document it 3 Some other humans read it 4 And program another component to use the interface
  25. API

  26. Roy Fielding

  27. REST ARCHITECTURAL STYLE

  28. SHARED UNDERSTANDING AHEAD OF TIME 1 EX PO SE IN

    TERFAC E W RITE D O C S REA D D O C S PRO G RA M C LIEN T 2 3 4
  29. SHARED UNDERSTANDING AHEAD OF TIME 1 EX PO SE IN

    TERFAC E W RITE D O C S REA D D O C S PRO G RA M C LIEN T 2 3 4
  30. GOLDEN AGE OF TURKS ~2016~

  31. All of us

  32. SHARED UNDERSTANDING AHEAD OF TIME 1 EX PO SE IN

    TERFAC E W RITE D O C S REA D D O C S PRO G RA M C LIEN T 2 3 4 what happens when one of these changes?
  33. PROBLEMS OF SHARED UNDERSTANDING AHEAD OF TIME • Error-prone •

    Brittle system • Tight-coupling, prohibits changes • Requires couple of iterations to get it right • Does not scale humans do errors versioning anyone? heard about broken clients? did clients use your API as expected? hire more programmers to write more docs
  34. WE CAN PREVENT OR MITIGATE MOST OF THESE

  35. 1 PREPA RATIO N API FLOW D ESIG N &

    PRO TO TYPE D EVELO PM EN T D ELIVERY C O N SU M PTIO N A N A LYSIS 2 3 4 5 6
  36. None
  37. apiary.io/how-to-build-api

  38. MECHANICAL TURK NO MORE ~1996/7~

  39. IBM DEEP BLUE

  40. 227 YEARS AFTER THE FIRST TURK

  41. PART II DOCUMENTATION ISN’T WHAT YOU THINK

  42. WHAT IS DOCUMENTATION?

  43. MARKETING TOOL DRIVING ADOPTION

  44. MOVE FAST AND BREAK THINGS WORLD

  45. THAT’S WHY WE HAVE SO MANY BROKEN THINGS

  46. MIND SHIFT

  47. DOCUMENTATION IS THINKING TOOL

  48. WHY IS NOT DOCUMENTATION TODAY A THINKING TOOL?

  49. OBFUSCATING WHAT MATTERS

  50. 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
  51. LET’S LOOK AT GITHUB EXAMPLE https://developer.github.com/v3/

  52. HOW TO DOCUMENT SYSTEM

  53. DOCUMENT WHAT NOT HOW

  54. DOCUMENT YOUR DATA

  55. DOCUMENT WHAT YOU CAN DO WITH THE DATA

  56. CONTROLLED VOCABULARY

  57. DESCRIBE YOUR DOMAIN SEMANTICS

  58. CLEAR THINKING leads to GOOD DESIGN

  59. LONGEVITY SCALEABILITY

  60. MACHINE INTEROPERABILITY

  61. UNTHINKABLE THOUGHTS ~1980~

  62. Richard Hamming

  63. The Unreasonable Effectiveness of Mathematics Just as there are odors

    that dogs can smell and we cannot, as well as sounds that dogs can hear and we cannot, so too there are wavelengths of light we cannot see and flavors we cannot taste. Why then, given our brains wired the way they are, does the remark, "Perhaps there are thoughts we cannot think," surprise you?
  64. DOCUMENTATION TO ENCOURAGE THINKING

  65. THANK YOU

  66. REFERENCE • apiary.io/how-to-build-api • http://goodapi.co/ • https://en.wikipedia.org/wiki/The_Turk • http://amundsen.com/blog/archives/1146 •

    http://www.kurzweilai.net/memorandum-for- members-and-affiliates-of-the-intergalactic-computer- network • https://en.wikipedia.org/wiki/Richard_Hamming