Leaping Forward: Finding The Future Of Your API Docs

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.

Writing API documentation at a fast-growing startup is hard. Small writing teams need to pick their battles and balance keeping pace with the product while elevating the developer experience. But a stale developer portal can erode confidence in your documentation just as quickly as outdated content. When a startup grows into an enterprise, it’s easy for past choices that made so much sense at the time—a great hire or the perfect tool—to come back and haunt you. How do you know when it’s time to reset? And how do you deliver your documentation’s next giant leap forward?

This talk will describe the unique origin of Marqeta’s API documentation, explain some of our missteps along the way, and provide a framework for fixing your biggest documentation pain points.

For more information about Marqeta, check out marqeta.com and marqeta.com/docs!

You can also follow @Marqeta and @aaronverber on Twitter.

Transcript

1. Leaping Forward Finding The Future Of Your API Docs
2. Why leap forward?
3. For API platforms, developer docs are essential!
7. Platform Complexity Time Required documentation
8. Platform Complexity Time Required documentation Productivity
9. Platform Complexity Time Required documentation (New hires) Productivity
10. Platform Complexity Time Required documentation Productivity (New hires) Actual documentation
11. Oakland, CA London, UK Aaron Verber Product Manager, Developer Relations
12. What goes in your “leap forward” toolkit?
13. History
14. In 2016, MARQETA became the first issuer-processor to publicly document its payments API
15. 2016 One writer in our marketing CMS
16. 2018 Four writers in our marketing CMS
18. 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.
19. Signs of trouble
20. 2020 Product Roadmap
21. 2016 Docs Pipeline
22. 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?
23. 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. • Survey writer satisfaction.
24. Pain points
25. No collaboration No version control No review tools Limited page size Limited organization options
26. What resources do our developers need? Payments Competency Technical Competency ★ Required competency for success Your awesome platform goes here Your developers (usually) start here
27. What resources do our developers need? Payments Competency Technical Competency ★ API Reference (2016)
28. What resources do our developers need? Payments Competency Technical Competency ★ API Reference (2016) Dev Guides (2017)
29. What resources do our developers need? Payments Competency Technical Competency ★ API Reference (2016) Dev Guides (2017) Tutorials (2018)
30. What resources do our developers need? Payments Competency Technical Competency ★ API Reference (2016) Dev Guides (2017) Tutorials (2018) Payments Basics SDKs (2019)
31. Solving pain points isn’t enough to leap forward.
32. Simple but powerful authoring Move docs closer to the code Prepare for automated tools Keep the source portable An existing ecosystem
33. Go beyond pain points. • What could you do with a new tool? Dream big! • Create a shared taxonomy describing your docs. • Demonstrate the added value with a prototype.
34. Prototypes
35. We chose Gatsby + AsciiDoc.
36. We chose Gatsby + AsciiDoc. (Eventually.)
37. 2017 Hack Week Prototype
38. 2018 AsciiDoc + Hugo Prototype
39. Why AsciiDoc?
40. Possibility space!
41. Humans can read the source. #1
44. Humans can read the source. #2 #1 There’s a healthy ecosystem.
45. Gatsby A static-site generator AsciiDoctor A text processor and plugin for Gatsby
46. GitHub A git host for version control Visual Studio Code A text editor
47. Humans can read the source. #2 #1 #3 There’s a healthy ecosystem. It can live near your code.
49. 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.
51. 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.
52. 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.
53. Practice
57. Use the migration to practice. • Document your tool using your tool. • Start a dedicated Slack channel. • Test your new publishing process. • Run user testing, too!
58. The Future
59. Content management system + Easy to use - Vendor-based ($$$) - Monolithic and bulky
60. 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
61. 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
62. Be thoughtful about the long-term writing experience and information architecture.
63. NOW COOL TOOL BETTER TOOL ...can you leverage this? If you over-develop this...
64. 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!
65. 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.
66. marqeta.com/docs
68. Thank you! @aaronverber @marqeta