Leaping Forward: Finding The Future of Your API Docs
•
0 j'aime•119 vues
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.
Recommandé
Recommandé
Contenu connexe
Tendances
Tendances (20)
Similaire à Leaping Forward: Finding The Future of Your API Docs
Similaire à Leaping Forward: Finding The Future of Your API Docs (20)
Plus de Pronovix
Plus de Pronovix (20)
Dernier
Dernier (20)
Leaping Forward: Finding The Future of Your API Docs
- 1. Leaping Forward Finding The Future Of Your API Docs
- 3. FUN!
- 5. For API platforms, developer docs are essential!
- 13. Oakland, CA London, UK Aaron Verber Product Manager, Developer Relations
- 14. What goes in your “leap forward” toolkit?
- 15. History
- 16. In 2016, MARQETA became the first issuer-processor to publicly document its payments API
- 17. 2016 One writer in our marketing CMS
- 18. 2018 Four writers in our marketing CMS
- 20. 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.
- 21. Signs of trouble
- 24. 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?
- 25. 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.
- 26. Pain points
- 27. No collaboration No version control No review tools Limited page size Limited organization options
- 28. What resources do our developers need? PaymentsCompetency Technical Competency ★ Required competency for success Your awesome platform goes here Your developers (usually) start here
- 29. What resources do our developers need? PaymentsCompetency Technical Competency ★ API Reference (2016)
- 30. What resources do our developers need? PaymentsCompetency Technical Competency ★ API Reference (2016) DevGuides(2017)
- 31. What resources do our developers need? PaymentsCompetency Technical Competency ★ API Reference (2016) DevGuides(2017) Tutorials (2018)
- 32. What resources do our developers need? PaymentsCompetency Technical Competency ★ API Reference (2016) DevGuides(2017) Tutorials (2018) PaymentsBasics SDKs (2019)
- 33. Simple but powerful authoring Move docs closer to the code Prepare for automated tools Keep the source portable An existing ecosystem
- 34. 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.
- 35. Prototypes
- 36. We chose Gatsby + AsciiDoc.
- 37. We chose Gatsby + AsciiDoc. (Eventually.)
- 38. 2017 Hack Week Prototype
- 39. 2018 AsciiDoc + Hugo Prototype
- 40. Why AsciiDoc?
- 42. Humans can read the source.#1
- 45. Humans can read the source. #2 #1 There’s a healthy ecosystem.
- 46. Gatsby A static-site generator AsciiDoctor A text processor and plugin for Gatsby
- 47. Gatsby A static-site generator AsciiDoctor A text processor and plugin for Gatsby
- 48. GitHub A git host for version control Visual Studio Code A text editor
- 49. GitHub A git host for version control Visual Studio Code A text editor
- 52. Humans can read the source. #2 #1 #3 There’s a healthy ecosystem. It can live near your code.
- 54. 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.
- 56. 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.
- 57. 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.
- 58. Practice
- 62. 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!
- 63. The Future
- 64. Content management system + Easy to use - Vendor-based ($$$) - Monolithic and bulky
- 65. 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
- 66. 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
- 67. Be thoughtful about the long-term writing experience and information architecture.
- 68. NOW COOL TOOL BETTER TOOL ...can you leverage this?If you over-develop this...
- 69. 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!
- 70. 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.