The document discusses the importance of documentation for cloud platforms and APIs. It notes that documentation makes the first impression for developers and is critical for onboarding. The rest of the document outlines best practices for API documentation, including having a getting started guide, searchable content, code examples, and keeping documentation up-to-date. It also discusses discovering APIs, learning how to use them, and how software development kits (SDKs) can help by addressing common tasks like authentication and rate limiting. The key message is that documentation is essential and "if software doesn't have good documentation, it isn't fully baked."

1. How Documentation
Can Make or Break Your
Cloud Platform
Doc or Die
Everett Toews
Developer Advocate
@everett_toews
Cloud Expo
June, 2013

2. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Intro
2
Developer

3. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Committer on jclouds
3

4. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Intro
4
Advocate

5. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Intro
5

6. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Intro
6
Operations

7. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Co-author of The OpenStack Operations Guide
7docs.openstack.org/ops

8. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Agenda
8

9. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
The Workshop
•Introduction
•Discovering an API
•Learning an API
•Defining Good Doc
•Creating Good Doc
•Bad Doc
•Software Development Kits
9

10. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Introduction
10

11. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Cloud Platforms
11

12. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Cloud Platforms
12
Infrastructure
as a Service

13. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Cloud Platforms
13
Platform
as a Service

14. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Cloud Platforms
14
Software
as a Service

15. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
jclouds Community
15
After 3 beer I
can able use
any of cloud
API.
@DevOps_Borat

16. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
API Boundary
16
Customer
System
Your Cloud
Platform
A
P
I
User
System

17. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
API Docs are really really really important
17
Source: http://blog.programmableweb.com/2013/01/07/api-consumers-want-reliability-documentation-and-community/

18. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
API Docs are Important to Developers
•Make
•First Impressions
•Onboarding
•Break
18

19. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Discovering an API
19

20. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Discovery
20
Your Landing Page

21. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Discovery
21
Google

22. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Discovery
22
StackOverflow

23. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Discovery
23
developer.rackspace.com
dev.rackspace.com

24. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Discovery
24
api.rackspace.com

25. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Learning an API
25

26. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Learning
26
Documentation

27. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Learning
27
Free Cloud Trial

28. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Learning
28
Minimum

29. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Learning
29
Trial and Error

30. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Learning
30
HTTP
curl

31. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Learning
31
JSON
jq

32. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Learning
32
Help

33. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
33

34. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
34
Getting Started Guide

35. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
35
Navigation

36. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Navigation
36

37. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Navigation
37

38. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Navigation
38

39. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
39
Searchable

40. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Searchable
40

41. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Searchable
41

42. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Searchable
42

43. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
43
Examples

44. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Examples
44

45. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Examples
45

46. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Examples
46

47. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
47
Law of entropy for
documentation: after
60 day, each piece of
documentation is
either invalid or can
not able be found.
@DevOps_Borat

48. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
48
Help

49. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Help
49

50. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Help
50

51. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Help
51

52. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
52
URLs Matter

53. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
URLs Matter
•docs.rackspace.com/servers/api/v2/cs-
devguide/content/CreateServers.html
•sendgrid.com/docs/API_Reference/Custo
mer_Subuser_API/account_limits.html
•stripe.com/docs/api/curl#update_plan
53

54. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
54
Up-To-Date

55. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Up-To-Date
•RSS/Atom
•Twitter
•Email
•G+/LinkedIn/Facebook
55

56. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
56
Topics

57. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Topics
•Introduction
•Endpoint
•Authentication
•Request/Response Format
•Errors
57

58. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Request/Response Format
•Parameter (and Position)
•Description
•Type (and Format)
•Default
•Range of Valid Values
•Required
58

59. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
59
More Topics

60. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
More Topics
•Versioning
•Release Notes
•Pagination
•Rate Limits
•Interactivity
•WADL
60

61. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
61
Consistent API

62. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
62
Consistent API Doc

63. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Defining Good Doc
63
“If it doesn’t have
good doc, the
software isn’t fully
baked.”

64. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Creating Good Doc
64

65. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Good Doc
65
Talent

66. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Good Doc
66
Handcrafted
vs
Handcrafted Tools

67. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Good Doc
67
Audience

68. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Good Doc
68
Perspective

69. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Good Doc
69
Platform
Developer
Engagement

70. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Creating Good Doc
70
Product
Improvement

71. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Good Doc
•Swagger
•apiary.io
•Mashery I/O Docs
71

72. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Good Doc
72
Low MTBIAMSH

73. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Good Doc
73
15 Minutes

74. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Bad Doc
74

75. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Bad Doc
75
!(Good Doc)

76. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Bad Doc
76
Inaccurate

77. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Bad Doc
77
Marketing

78. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Bad Doc
78
Don’t Call Me

79. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Bad Doc
79
Twitter Rants

80. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
Software Development Kits
80

81. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
81
Customer
System
S
D
K
Your Cloud
Platform
A
P
I
User
System

82. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
82
Plumbing

83. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
83
(Re)Authentication

84. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
84
Pagination

85. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
85
State Polling

86. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
86
Rate Limiting

87. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
87
Retry

88. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
88
Smoothing
Rough Edges

89. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
89
Open Source

90. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
90
In devops
nobody is get
fire for buy
open source.
@DevOps_Borat

91. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
91
Community

92. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
92
Packaged

93. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
93
All-in-one

94. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
94
Battle Tested Code

95. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
95
Example Code

96. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
96
Documentation

97. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
97

98. RACKSPACE® HOSTING | WWW.RACKSPACE.COM
SDKs
98
Survey is show
junior devops
are still believe
in Tooth Fairy,
Santa Claus and
documentation. @DevOps_Borat

99. Thank You
Everett Toews
Developer Advocate
@everett_toews
developer.rackspace.com
sdk-support@rackspace.com
j.mp/doc-or-die