Write your developer docs in AsciiDoc

At Marqeta, we’re always thinking about how we can elevate the developer experience. We’re focused on providing the best resources and tools to help innovative businesses build and maintain integrations with the Marqeta payments platform.

To help level up our developer experience, we recently released our brand new developer documentation site. On the front end, it features a new clean look, clear navigation, a direct line for sharing feedback, and the same high-quality content developers expect.

On the back end, though, the changes are more revolutionary.

I recently spoke at the JAMstack SF meetup about how Marqeta uses Gatsby and AsciiDoc — complete with a live demo and a selfie to prove it!

A standard, not a CMS

When given the opportunity to build something new, it’s easy for content creators to fall into the “Which CMS now?” trap. As in, “Now that we have the chance to recreate our documentation site from scratch, which system-first, content-second tool should we push through the vendor approval process?”

“It does most of what we want,” you hear yourself saying. “We’ll have to reorganize our content to make it fit, but then we’ll be done. So our links won’t work, and there’s no content reuse. It won’t be too bad, right?” You’re not even saying the words anymore. They’re just falling out of your mouth.

The writer next to you squeaks with terror. “I’m on their pricing page. Is that per year or per month?”

“Per seat.”

“Oh dear.”

Stop! Don’t play the content management system game. Consider that your documentation woes might not be because of the CMS you chose, but because you chose a CMS at all.

When Marqeta’s team of technical writers started gathering requirements for our new docs authoring toolchain, we reviewed a lot of different content management systems. We were looking for something to help us move beyond our existing CMS. It had served our docs well for years but had recently grown too restrictive. Now we had a bigger team and the tech writers were bumping into each other. Without proper collaboration and version control tools, we were always one misstep away from inadvertently overwriting someone else’s changes.

Think about how much of your day is defined by how you feel about your primary work tool. Living with the constant dread of blocking someone from releasing new docs, or worse, deleting all their hard work, isn’t a great feeling to have hanging over you.

I’m a big fan of prototyping. For each CMS we investigated, I would sign up for a demo account and rebuild a part of our documentation. It’s a great method to explore the features and limitations of a tool. And the hard truth I kept running into over and over again was that none of these content management systems came close to how well tried-and-true tools like a text editor and git work.

Our search for a replacement CMS had started us on the wrong path. We were taking a step left or right when what we wanted was a step forward. To do that, we decided to drop the CMS altogether.

AsciiDoc in Visual Studio Code

What a source-first approach looks like

Documentation, like any creative process, requires precision input and a large canvas. It’s not enough for a composer to write down the notes of a song — there are critical annotations in all music that impart the full intended performance of a song. Modern documentation, especially developer documentation, requires a similar level of precision.

It’s important to note that content management systems aren’t bad, but too many times they’re adopted too soon, and your desired content structure crumbles to the limitations of your CMS. Instead, give your content a chance to grow on its own first. Leave the training wheels at home and go straight to the source. The source is your precision documentation instrument.

At Marqeta, the tech writing team decided to take a source-first, standards-based approach. We tried static site generators like Gatsby and Hugo that transform markup languages like Markdown into HTML. With Markdown, you can author and edit the content source of your website directly with a relatively straight-forward syntax to define things like headers, lists, and web links. But we also knew we weren’t limited to Markdown — Gatsby lets you pick from multiple formats to use as your content source.

Why source-first? Why a standard? When we considered the past, present, and future of our documentation, we knew we wanted to avoid over-investing in any one system while maintaining a long-lasting single source of truth. To ensure the long-term flexibility of our content, provide a great authoring experience for our technical writers, and deliver the best possible documentation to our developer audience, we kept the following principles in mind when building our new toolchain:

1. Humans can read the source. When I open the source file without using my authoring tool or CMS, I can still read the documentation. It’s so handy, but so many tools go so far to hide or obfuscate the source. And don’t you dare charge me for the privilege!
2. There is a healthy ecosystem. The source can be written, edited, saved, viewed, and transformed by multiple tools. The more tools, the better! The larger the ecosystem, the more you can play with different combinations. Things to look for include static site generators, text editors, version control systems, and plug-ins in general.
3. It lives near the code. Maybe your docs live in their own repository, or they live in the same repository as your code. But keeping your source files where you keep your code (usually git) enables all kinds of synergy. You can learn more about the “docs as code” movement here.
4. It’s portable and convertible. Your chosen standard may be the best, most powerful standard available today, but nothing lasts forever, and you want to ensure you can transition easily to the Next Big Thing. That means being able to painlessly convert your documentation from one format to another.
5. It’s free and you own your content. As a writer, you should always keep in mind who you let own or license your content. A lot of fee-based CMS tools now claim that you own all of your content now and forever. Then they follow it up with a 50-page End User License Agreement (EULA) that says, actually, they get to license your content for advertisements, social media, and whatever else they want. For smaller organizations, this might not be a big deal. But for enterprise-level organizations, you can be sure the legal team is thinking about these things.

Photo by Andy Holmes on Unsplash

AsciiDoc for flexible, source-powered documentation

The best canvas for creating your documentation is AsciiDoc. With AsciiDoc, a technical writer has a huge possibility space to work inside.

I could list off the dozens of great features that make AsciiDoc essential to a technical writer’s toolkit, but it’s the possibility space that is most satisfying for technical writers. What does that mean?

• Near unlimited organization options mean you can make choices that best fit your documentation. Add and arrange sections and subsections how you like them, as many as you want. Want to embed a bulleted list of tables inside another table? Go for it (but also please don’t). You also get admonitions, annotations, images, video, and audio out of the box. If you can dream it, AsciiDoc can do it
• Reusable content makes single source of truth a reality. Why manually write the same note on every page of your docs when you can write it once as a snippet and include it where you want with super simple syntax?
• The ability to extend AsciiDoc with your own syntax and custom content blocks means you can define and style the elements of documentation that are important to you. Maybe you want to build a custom syntax to add tabs to your document. Or you already have a widget you want to embed in multiple places. You can do it!

So how does AsciiDoc fit into the requirements I outlined earlier? Let’s see:

1. Human-readable? AsciiDoc is an incredibly legible format to author, edit, and read. Most of the standard syntax follows the rules of Markdown, so if you can read that, you can read this.
2. Ecosystem? The AsciiDoc ecosystem is hot! Do you use Gatsby? GitHub? Visual Studio Code? They all support AsciiDoc, either natively or with a plug-in. GitHub renders AsciiDoc natively on their website, so it’s easy to read through and comment on documentation from inside a pull request.
3. Lives near code? Depending on your toolchain, you can keep your AsciiDoc files where you like, whether that’s in their own repository, a shared repository with the rest of your doc site code, or a shared repository with your platform’s production code — it’s all possible!
4. Convertible? One of the strengths of AsciiDoc is that it’s based on DocBook, a long-lived XML standard, meaning you can easily convert AsciiDoc to DocBook, and then into dozens of other file formats using a tool like pandoc. And AsciiDoc natively converts to PDF, HTML, LaTeX, and more.
5. Free and doesn’t claim your content? AsciiDoc (the format) and AsciiDoctor (the text processor) are both free, open-source, and regularly maintained. No vendor pricing. No EULA. It’s all yours!

So how do I do it?

Are you ready? I’d be lying if I said the AsciiDoc toolchain was as easy to use as a CMS. But if you are willing to put in a little learning time with a wildly powerful paintbrush and canvas, you will be greatly rewarded.

It starts here:

1. npm install -g gatsby-cli installs Gatsby.
2. npm install -g asciidoctor installs AsciiDoctor, the text processor that reads AsciiDoc files.
3. npm install -g gatsby-transformer-asciidoc installs the plugin that enables Gatsby to use AsciiDoctor to read AsciiDoc source files.
4. gatsby new gatsby-site creates a new site called gatsby-site.
5. cd gatsby-site opens your gatsby-site directory.
6. gatsby develop builds a local copy of your site that hot-reloads with every change you make to the content.
7. localhost:8000 is the address of your local server.

There are plenty of Gatsby templates to choose from to start your documentation site. You can also clone one of the many starter site repositories out there, like ericwindmill’s Gatsby Starter Docs project.

I highly suggest keeping your site on GitHub. Using a high-powered version control system for your documentation makes a big difference when you want to figure out who edited your Perfect Paragraph six months ago.

For quick deployments, especially during the prototyping phase, check out Netlify. It’s a new form of magic that plugs into your GitHub repo and deploys your code in seconds.

What else do you need?

• Some assembly required. You’ll need to glue together a few more pieces using AsciiDoc than a traditional CMS, but that’s half the fun! Gatsby templates will get you started, and from there, the power is in your hands!
• Some training required. No CMS means no WSYWIG editor — you’re welcome! But to leverage all the great things AsciiDoc can do for you, you’ll want to read their full documentation or syntax quick reference guide. Of course, it’s all written in AsciiDoc.
• Some self-control required. After you see the power AsciiDoc gives you, it’s easy to go overboard. First, take a deep breath. Then, work on establishing a strong foundation first — aim for parity with your current docs. After you are more familiar with your toolchain, you can start making bigger steps forward!

Where do developer docs go from here?

Put simply, more automation — cliche as it is. As the platform you are documenting grows both in breadth and depth, you need to find ways of maximizing your writers’ contributions, and that means handing off some of the more straightforward tasks to the build process.

Specs like OpenAPI (aka Swagger) enable you to define the shape and rules of your API in a way that practically writes the documentation itself (though not quite). Plug your shiny new auto-generated API reference documentation into your hand-written tutorials and guides, write a script to start generating code samples dynamically based on the actual production API environment, and now you’re cooking up complete, accurate documentation built on a modern toolchain.

After you’ve established a robust foundation in AsciiDoc and have mastered your toolchain, you can start thinking even crazier things. Like, why have one documentation site when you could build one in each language you want to support? Or for each version of your API? You could even go wild and generate a custom documentation site for every user, personalized for them. The possibilities go on and on.

Follow us

Aaron Verber is the Product Manager for Developer Relations at Marqeta. You can follow him on Twitter and LinkedIn.

Follow Marqeta on Twitter for all the latest news and updates. And if you haven’t heard, we’re growing! Come work with us and help build a modern payments platform for the world’s innovators!