Turks, Aliens and Thinking

Deck for talk I gave at combined Write the Docs and API Craft SF meetup

http://www.meetup.com/Write-the-Docs-SF/events/233381669/

http://www.meetup.com/API-Craft-San-Francisco/events/233267541/

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