Modern docs for a modern payments API at PAYMENTSfn New York

Last month, I had the opportunity to speak at the PAYMENTSfn meetup in New York, NY about how Marqeta delivers modern, high-quality developer documentation for our payments platform. The group brings together technical payments professionals to hear informative talks and socialize with peers in the industry. It was awesome to meet so many new people, hear about their careers, and talk about how essential modern documentation is for payments.

In the payments ecosystem, modern documentation is essential for two reasons:

• To build multiple required competencies across payments and development.
• To grow and adapt your docs at scale (while keeping costs down).

Building competencies

Successfully developing for payments requires knowledge in multiple competencies. It’s not enough to know how to use an API if the concepts you’re working with don’t make sense. That’s why the Marqeta platform documentation has grown over time to include multiple types of documentation:

• The Core API Reference explains the functionality of our payments platform.
• The DiVA API Reference documents our data analytics and reporting API.
• Our Developer Guides connect our API resources to real-world payments ecosystem concepts.

Depending on your use case, you might also think about additional documentation like a glossary or FAQ. Developers have diverse backgrounds with a wide range of skills and experiences. Your documentation needs to close the gap between learning and succeeding for every developer.

Try mapping the gap between what your users need to know and what your current documentation realistically achieves.

Scaling content

To write and manage all of this, your documentation needs to grow and scale, while hopefully keeps costs under control. At Marqeta, we’ve recently launched the beta of our new documentation site powered by Gatsby and AsciiDoc.

• Gatsby is a static site generator that enables us to deliver a high-quality, customizable, and scalable documentation experience.
• AsciiDoc is a markup language that makes it easy to author detailed, well-formatted documentation.

Tools like Gatsby and AsciiDoc are incredibly flexible and extensible, which helps them grow and change with your docs. They’re part of larger ecosystem of tools including GitHub, Drone, and VSCode, which all work really well with the toolchain. Plus, they’re free to use and fast to learn.

The Gatsby + AsciiDoc toolchain also creates a great jumping-off point for moving into a more spec-driven documentation generation utilizing OpenAPI and its ecosystem of tools. It’s important to think ahead about how your documentation will be powered in the future!

My evening with PAYMENTSfn was a lot of fun. It was great to see so many people interested in learning about modern tools for payments documentation.

Follow us

Follow me on Twitter at @aaronverber to hear more about how Marqeta is advancing the developer experience and sharing what we’ve learned. And check out @marqeta on Twitter for more news and updates.