Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Leaping Forward: Finding The Future of Your API Docs

17 views

Published on

Learn how to scale beyond old choices and find the next big thing for your API documentation. This talk will use the past, present, and future of Marqeta’s docs to provide a framework for growing and evolving your own.

Published in: Technology
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (2019 Update) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download Full EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download Full doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download PDF EBOOK here { https://soo.gd/irt2 } ......................................................................................................................... Download EPUB Ebook here { https://soo.gd/irt2 } ......................................................................................................................... Download doc Ebook here { https://soo.gd/irt2 } ......................................................................................................................... ......................................................................................................................... ................................................................................................................................... eBook is an electronic version of a traditional print book THIS can be read by using a personal computer or by using an eBook reader. (An eBook reader can be a software application for use on a computer such as Microsoft's free Reader application, or a book-sized computer THIS is used solely as a reading device such as Nuvomedia's Rocket eBook.) Users can purchase an eBook on diskette or CD, but the most popular method of getting an eBook is to purchase a downloadable file of the eBook (or other reading material) from a Web site (such as Barnes and Noble) to be read from the user's computer or reading device. Generally, an eBook can be downloaded in five minutes or less ......................................................................................................................... .............. Browse by Genre Available eBooks .............................................................................................................................. Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, ......................................................................................................................... ......................................................................................................................... .....BEST SELLER FOR EBOOK RECOMMEND............................................................. ......................................................................................................................... Blowout: Corrupted Democracy, Rogue State Russia, and the Richest, Most Destructive Industry on Earth,-- The Ride of a Lifetime: Lessons Learned from 15 Years as CEO of the Walt Disney Company,-- Call Sign Chaos: Learning to Lead,-- StrengthsFinder 2.0,-- Stillness Is the Key,-- She Said: Breaking the Sexual Harassment Story THIS Helped Ignite a Movement,-- Atomic Habits: An Easy & Proven Way to Build Good Habits & Break Bad Ones,-- Everything Is Figureoutable,-- What It Takes: Lessons in the Pursuit of Excellence,-- Rich Dad Poor Dad: What the Rich Teach Their Kids About Money THIS the Poor and Middle Class Do Not!,-- The Total Money Makeover: Classic Edition: A Proven Plan for Financial Fitness,-- Shut Up and Listen!: Hard Business Truths THIS Will Help You Succeed, ......................................................................................................................... .........................................................................................................................
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

Leaping Forward: Finding The Future of Your API Docs

  1. 1. Leaping Forward Finding The Future Of Your API Docs
  2. 2. FUN!
  3. 3. Why leap forward?
  4. 4. For API platforms, developer docs are essential!
  5. 5. PlatformComplexity Time Required documentation
  6. 6. PlatformComplexity Time Required documentation Productivity
  7. 7. PlatformComplexity Time Required documentation(New hires) Productivity
  8. 8. PlatformComplexity Time Required documentation Productivity (New hires) Actual documentation
  9. 9. Oakland, CA London, UK Aaron Verber Product Manager, Developer Relations
  10. 10. What goes in your “leap forward” toolkit?
  11. 11. History
  12. 12. In 2016, MARQETA became the first issuer-processor to publicly document its payments API
  13. 13. 2016 One writer in our marketing CMS
  14. 14. 2018 Four writers in our marketing CMS
  15. 15. Know the history. ● Ask who wrote the original docs. ● Ask who built the original tools. ● Keep a record of the docs history. ● Use tools like archive.org to take a look back.
  16. 16. Signs of trouble
  17. 17. 2020 Product Roadmap
  18. 18. 2016 Docs Pipeline
  19. 19. Do you: ● Create fragile processes to cover tool gaps? ● Worry about overwriting unpublished work? ● Avoid certain docs because the tool is too difficult? ● Prefer writing docs outside your tool?
  20. 20. Watch for signs of trouble. ● Avoid bad processes meant to cover tool gaps. ● Avoid needing to work outside your tool. ● Track unintended or undesirable outcomes.
  21. 21. Pain points
  22. 22. No collaboration No version control No review tools Limited page size Limited organization options
  23. 23. What resources do our developers need? PaymentsCompetency Technical Competency ★ Required competency for success Your awesome platform goes here Your developers (usually) start here
  24. 24. What resources do our developers need? PaymentsCompetency Technical Competency ★ API Reference (2016)
  25. 25. What resources do our developers need? PaymentsCompetency Technical Competency ★ API Reference (2016) DevGuides(2017)
  26. 26. What resources do our developers need? PaymentsCompetency Technical Competency ★ API Reference (2016) DevGuides(2017) Tutorials (2018)
  27. 27. What resources do our developers need? PaymentsCompetency Technical Competency ★ API Reference (2016) DevGuides(2017) Tutorials (2018) PaymentsBasics SDKs (2019)
  28. 28. Simple but powerful authoring Move docs closer to the code Prepare for automated tools Keep the source portable An existing ecosystem
  29. 29. Go beyond pain points. ● What could you do with a new tool? Dream big! ● Create a shared taxonomy describing your docs. ● Communicate! ● Demonstrate the added value with a prototype.
  30. 30. Prototypes
  31. 31. We chose Gatsby + AsciiDoc.
  32. 32. We chose Gatsby + AsciiDoc. (Eventually.)
  33. 33. 2017 Hack Week Prototype
  34. 34. 2018 AsciiDoc + Hugo Prototype
  35. 35. Why AsciiDoc?
  36. 36. Possibility space!
  37. 37. Humans can read the source.#1
  38. 38. Humans can read the source. #2 #1 There’s a healthy ecosystem.
  39. 39. Gatsby A static-site generator AsciiDoctor A text processor and plugin for Gatsby
  40. 40. Gatsby A static-site generator AsciiDoctor A text processor and plugin for Gatsby
  41. 41. GitHub A git host for version control Visual Studio Code A text editor
  42. 42. GitHub A git host for version control Visual Studio Code A text editor
  43. 43. Humans can read the source. #2 #1 #3 There’s a healthy ecosystem. It can live near your code.
  44. 44. Humans can read the source. #2 #1 #3 #4 There’s a healthy ecosystem. It can live near your code. It’s convertible and portable.
  45. 45. Humans can read the source. #2 #1 #3 #4 #5 There’s a healthy ecosystem. It can live near your code. It’s convertible and portable. It’s free and you own your content.
  46. 46. Build your own prototype. ● Limit risk by putting your plan into action early. ● Give yourself time to find and reject the wrong tools. ● Keep in mind any third-party content policies. ● Use tools like Stackbit and Netlify to try SSGs.
  47. 47. Practice
  48. 48. Use the transition to practice. ● Document your tool using your tool. ● Start a dedicated Slack channel. ● Test your new publishing process. ● Run user testing, too!
  49. 49. The Future
  50. 50. Content management system + Easy to use - Vendor-based ($$$) - Monolithic and bulky
  51. 51. AsciiDoc-based toolchain + Extensible & testable + Standards-based - Assembly required Content management system + Easy to use - Vendor-based ($$$) - Monolithic and bulky is here! Gatsby Static site generator AsciiDoc Markup syntax GitHub Version control Drone CI/CD
  52. 52. API spec-based toolchain + Automates multiple outputs + Source of truth = code = docs - Organizational buy-in required AsciiDoc-based toolchain + Extensible & testable + Standards-based - Assembly required Content management system + Easy to use - Vendor-based ($$$) - Monolithic and bulky is here! OpenAPI API spec Your API Docs + code samples SDKs, Postman, etc. Gatsby Static site generator AsciiDoc Markup syntax GitHub Version control Drone CI/CD
  53. 53. Be thoughtful about the long-term writing experience and information architecture.
  54. 54. NOW COOL TOOL BETTER TOOL ...can you leverage this?If you over-develop this...
  55. 55. Plan for the future. ● Choose tools that can grow and adapt with you. ● Don’t over-invest in any one tool or format. ● Build in phases toward your end goal. ● Keep dreaming up the next big improvements!
  56. 56. Your giant leap toolkit 1. Know the history of your docs site, tool, and team. 2. Track any signs that you’re digging yourself into a hole. 3. Go beyond pain points to show added value. 4. Build your own prototype. 5. Use the transition to practice. 6. Plan for the future to make your next leap easier.
  57. 57. Thanks! @aaronverber @marqeta

×