Doc or Die

522 views

Published on

Published in: Technology, Business
0 Comments
1 Like
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
522
On SlideShare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
0
Comments
0
Likes
1
Embeds 0
No embeds

No notes for slide
  • Why did Rackspace utilize cross-cloud toolkits?Lock-on, not lock-in
  • Mean Time Between Idea and Making Stuff Happen
  • Doc or Die

    1. 1. How DocumentationCan Make or Break YourCloud PlatformDoc or DieEverett ToewsDeveloper Advocate@everett_toewsCloud ExpoJune, 2013
    2. 2. RACKSPACE® HOSTING | WWW.RACKSPACE.COMIntro2Developer
    3. 3. RACKSPACE® HOSTING | WWW.RACKSPACE.COMCommitter on jclouds3
    4. 4. RACKSPACE® HOSTING | WWW.RACKSPACE.COMIntro4Advocate
    5. 5. RACKSPACE® HOSTING | WWW.RACKSPACE.COMIntro5
    6. 6. RACKSPACE® HOSTING | WWW.RACKSPACE.COMIntro6Operations
    7. 7. RACKSPACE® HOSTING | WWW.RACKSPACE.COMCo-author of The OpenStack Operations Guide7docs.openstack.org/ops
    8. 8. RACKSPACE® HOSTING | WWW.RACKSPACE.COMAgenda8
    9. 9. RACKSPACE® HOSTING | WWW.RACKSPACE.COMThe Workshop•Introduction•Discovering an API•Learning an API•Defining Good Doc•Creating Good Doc•Bad Doc•Software Development Kits9
    10. 10. RACKSPACE® HOSTING | WWW.RACKSPACE.COMIntroduction10
    11. 11. RACKSPACE® HOSTING | WWW.RACKSPACE.COMCloud Platforms11
    12. 12. RACKSPACE® HOSTING | WWW.RACKSPACE.COMCloud Platforms12Infrastructureas a Service
    13. 13. RACKSPACE® HOSTING | WWW.RACKSPACE.COMCloud Platforms13Platformas a Service
    14. 14. RACKSPACE® HOSTING | WWW.RACKSPACE.COMCloud Platforms14Softwareas a Service
    15. 15. RACKSPACE® HOSTING | WWW.RACKSPACE.COMjclouds Community15After 3 beer Ican able useany of cloudAPI.@DevOps_Borat
    16. 16. RACKSPACE® HOSTING | WWW.RACKSPACE.COMAPI Boundary16CustomerSystemYour CloudPlatformAPIUserSystem
    17. 17. RACKSPACE® HOSTING | WWW.RACKSPACE.COMAPI Docs are really really really important17Source: http://blog.programmableweb.com/2013/01/07/api-consumers-want-reliability-documentation-and-community/
    18. 18. RACKSPACE® HOSTING | WWW.RACKSPACE.COMAPI Docs are Important to Developers•Make•First Impressions•Onboarding•Break18
    19. 19. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDiscovering an API19
    20. 20. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDiscovery20Your Landing Page
    21. 21. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDiscovery21Google
    22. 22. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDiscovery22StackOverflow
    23. 23. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDiscovery23developer.rackspace.comdev.rackspace.com
    24. 24. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDiscovery24api.rackspace.com
    25. 25. RACKSPACE® HOSTING | WWW.RACKSPACE.COMLearning an API25
    26. 26. RACKSPACE® HOSTING | WWW.RACKSPACE.COMLearning26Documentation
    27. 27. RACKSPACE® HOSTING | WWW.RACKSPACE.COMLearning27Free Cloud Trial
    28. 28. RACKSPACE® HOSTING | WWW.RACKSPACE.COMLearning28Minimum
    29. 29. RACKSPACE® HOSTING | WWW.RACKSPACE.COMLearning29Trial and Error
    30. 30. RACKSPACE® HOSTING | WWW.RACKSPACE.COMLearning30HTTPcurl
    31. 31. RACKSPACE® HOSTING | WWW.RACKSPACE.COMLearning31JSONjq
    32. 32. RACKSPACE® HOSTING | WWW.RACKSPACE.COMLearning32Help
    33. 33. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc33
    34. 34. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc34Getting Started Guide
    35. 35. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc35Navigation
    36. 36. RACKSPACE® HOSTING | WWW.RACKSPACE.COMNavigation36
    37. 37. RACKSPACE® HOSTING | WWW.RACKSPACE.COMNavigation37
    38. 38. RACKSPACE® HOSTING | WWW.RACKSPACE.COMNavigation38
    39. 39. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc39Searchable
    40. 40. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSearchable40
    41. 41. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSearchable41
    42. 42. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSearchable42
    43. 43. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc43Examples
    44. 44. RACKSPACE® HOSTING | WWW.RACKSPACE.COMExamples44
    45. 45. RACKSPACE® HOSTING | WWW.RACKSPACE.COMExamples45
    46. 46. RACKSPACE® HOSTING | WWW.RACKSPACE.COMExamples46
    47. 47. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs47Law of entropy fordocumentation: after60 day, each piece ofdocumentation iseither invalid or cannot able be found.@DevOps_Borat
    48. 48. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc48Help
    49. 49. RACKSPACE® HOSTING | WWW.RACKSPACE.COMHelp49
    50. 50. RACKSPACE® HOSTING | WWW.RACKSPACE.COMHelp50
    51. 51. RACKSPACE® HOSTING | WWW.RACKSPACE.COMHelp51
    52. 52. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc52URLs Matter
    53. 53. RACKSPACE® HOSTING | WWW.RACKSPACE.COMURLs Matter•docs.rackspace.com/servers/api/v2/cs-devguide/content/CreateServers.html•sendgrid.com/docs/API_Reference/Customer_Subuser_API/account_limits.html•stripe.com/docs/api/curl#update_plan53
    54. 54. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc54Up-To-Date
    55. 55. RACKSPACE® HOSTING | WWW.RACKSPACE.COMUp-To-Date•RSS/Atom•Twitter•Email•G+/LinkedIn/Facebook55
    56. 56. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc56Topics
    57. 57. RACKSPACE® HOSTING | WWW.RACKSPACE.COMTopics•Introduction•Endpoint•Authentication•Request/Response Format•Errors57
    58. 58. RACKSPACE® HOSTING | WWW.RACKSPACE.COMRequest/Response Format•Parameter (and Position)•Description•Type (and Format)•Default•Range of Valid Values•Required58
    59. 59. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc59More Topics
    60. 60. RACKSPACE® HOSTING | WWW.RACKSPACE.COMMore Topics•Versioning•Release Notes•Pagination•Rate Limits•Interactivity•WADL60
    61. 61. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc61Consistent API
    62. 62. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc62Consistent API Doc
    63. 63. RACKSPACE® HOSTING | WWW.RACKSPACE.COMDefining Good Doc63“If it doesn’t havegood doc, thesoftware isn’t fullybaked.”
    64. 64. RACKSPACE® HOSTING | WWW.RACKSPACE.COMCreating Good Doc64
    65. 65. RACKSPACE® HOSTING | WWW.RACKSPACE.COMGood Doc65Talent
    66. 66. RACKSPACE® HOSTING | WWW.RACKSPACE.COMGood Doc66HandcraftedvsHandcrafted Tools
    67. 67. RACKSPACE® HOSTING | WWW.RACKSPACE.COMGood Doc67Audience
    68. 68. RACKSPACE® HOSTING | WWW.RACKSPACE.COMGood Doc68Perspective
    69. 69. RACKSPACE® HOSTING | WWW.RACKSPACE.COMGood Doc69PlatformDeveloperEngagement
    70. 70. RACKSPACE® HOSTING | WWW.RACKSPACE.COMCreating Good Doc70ProductImprovement
    71. 71. RACKSPACE® HOSTING | WWW.RACKSPACE.COMGood Doc•Swagger•apiary.io•Mashery I/O Docs71
    72. 72. RACKSPACE® HOSTING | WWW.RACKSPACE.COMGood Doc72Low MTBIAMSH
    73. 73. RACKSPACE® HOSTING | WWW.RACKSPACE.COMGood Doc7315 Minutes
    74. 74. RACKSPACE® HOSTING | WWW.RACKSPACE.COMBad Doc74
    75. 75. RACKSPACE® HOSTING | WWW.RACKSPACE.COMBad Doc75!(Good Doc)
    76. 76. RACKSPACE® HOSTING | WWW.RACKSPACE.COMBad Doc76Inaccurate
    77. 77. RACKSPACE® HOSTING | WWW.RACKSPACE.COMBad Doc77Marketing
    78. 78. RACKSPACE® HOSTING | WWW.RACKSPACE.COMBad Doc78Don’t Call Me
    79. 79. RACKSPACE® HOSTING | WWW.RACKSPACE.COMBad Doc79Twitter Rants
    80. 80. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSoftware Development Kits80
    81. 81. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs81CustomerSystemSDKYour CloudPlatformAPIUserSystem
    82. 82. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs82Plumbing
    83. 83. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs83(Re)Authentication
    84. 84. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs84Pagination
    85. 85. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs85State Polling
    86. 86. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs86Rate Limiting
    87. 87. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs87Retry
    88. 88. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs88SmoothingRough Edges
    89. 89. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs89Open Source
    90. 90. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs90In devopsnobody is getfire for buyopen source.@DevOps_Borat
    91. 91. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs91Community
    92. 92. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs92Packaged
    93. 93. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs93All-in-one
    94. 94. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs94Battle Tested Code
    95. 95. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs95Example Code
    96. 96. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs96Documentation
    97. 97. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs97
    98. 98. RACKSPACE® HOSTING | WWW.RACKSPACE.COMSDKs98Survey is showjunior devopsare still believein Tooth Fairy,Santa Claus anddocumentation. @DevOps_Borat
    99. 99. Thank YouEverett ToewsDeveloper Advocate@everett_toewsdeveloper.rackspace.comsdk-support@rackspace.comj.mp/doc-or-die

    ×