The Importance of Documentation in B2B API Adoption
Editor’s Note: This time around we have a new post from Anila Zaidi who previously wrote an informative series of posts about best practices for excellent technical writing. No spoilers, but as Anila mentions toward the bottom of this post, good docs are no less relevant today than they were yesterday, even in an AI-assisted era of software development. Enjoy!
We read reviews before buying a TV, a sweater, almost anything. Businesses do the same – potential enterprise partners evaluate APIs through every piece of content they come across. So, what happens when you improve all of it?
When the Commerce team and I improved our public Commerce API documentation, support tickets dropped by almost half. But I kept wondering whether better documentation could do more than reduce questions. Our Domain Reseller API gave me the answer.
In this post, I want to share how technical documentation went from basic support material to a product asset, and what it does for business-to-business (B2B) APIs: it decreases support questions, creates alignment across teams, and gives potential partners something concrete to evaluate before any decision is made.
Basic Docs Work… Until They Don't
In late 2023, Squarespace closed its acquisition of Google Domains. Overnight, the technical reality shifted. We had to replace the reseller API from Google Domains – the one Google Workspace and Google Cloud used to purchase domains – making them our first reseller partners.
Teams across Squarespace, Google Domains, Google Workspace, and Google Cloud worked together to create the new Reseller API. Questions were answered directly. Context lived in meetings and conversations. Because explaining the API happened through one-on-one communication, basic endpoint documentation was enough.
That changed when the Reseller API grew, and the gap between what the documentation said and what partners needed to know also grew.
A Working Document is Never a Workflow
The Reseller API was changing fast, much faster than the updates in the basic endpoint documentation. It didn’t take many sprints for the API response descriptions to fall out of sync with how the API actually worked. When partner questions increased, Squarespace engineers spent more time answering them – and everyone knew something had to change.
Twice a week, I met with engineers, testers, and a product manager to build a glossary for the Reseller API and a working dictionary of its models. We reviewed parameters one by one: what a field meant, when it appeared, what values were allowed, what null meant in context, and what partner developers should expect to see in responses. But, even the weeks we met three times a week, we still couldn’t keep pace with active development.
The dictionary was a working document, not a process.
Content Close to Code is Easier to Update
Because several of us had past success with docs-as-code, we moved the descriptions in the dictionary into API specification files stored in the same repository as the code. I also worked with Developer Relations to introduce a static-site generator. This tool pulls content from a repository, often in API specification and Markdown files, adds styles, and then generates static HTML documentation pages.
Now, endpoint documentation was easier to keep in sync because it was stored close to its implementation. And, guides were easier to update because the content was in Markdown files and part of the development workflow.
Partner developers moved between endpoint details and higher-level guidance without reading conflicting descriptions of the same model or field. That consistency mattered internally, too. Engineers spent less time answering the same questions about response data that should have been clear in the documentation.
Writing Exposes What Conversation Hides
When we met twice a week to work through the parameters in the Reseller API dictionary, the same conversation often happened. The engineers and testers in the room would explain how the API worked, while product managers and Business Development described how it should work.
The gap between those two explanations was often small in wording, yet significant in practice. Writing made those gaps impossible to ignore. That was my signal.
I used AI and industry resources to understand what reselling is and how it works in B2B commerce, how other registrars structure domain resale, and what partner developers consider when integrating registrar APIs. The goal was not expertise for its own sake, but fluency. That fluency let me ask more precise questions, surface assumptions between engineers and Business Development, and advocate for changes in the API that better aligned technical behavior with business expectations.
From there, I drafted a concise API overview and a single get-started guide for test integrations. I then shared these documents with all stakeholders, not just for confirmation, but to create a shared understanding of how the Reseller API actually worked. These guides were educational in the broadest sense: they clarified the API for everyone involved, gave internal teams a shared reference, and gave Business Development language that matched the technical reality of the product.
Squarespace engineers went on to use the guides as onboarding material for other engineers. Meanwhile, Business Development shared the guides with potential partners as a way to introduce the API.
Context Turns Integration Into Adoption
“An API should document itself.” In a perfect world, this philosophy would hold. In a not-so-perfect world where development is rapid, code is complex, and developers are sometimes globally distributed, contextual guides are what turn API integration into API adoption.
But how much context does a developer need? It’s a balance between what a developer needs to understand before writing a single line of code, and what they need to do to complete their first integration – without support.
For the Reseller API, that meant three content types:
Fundamentals that explained reselling concepts before a developer wrote a single line of code
How-to guides that walked through common workflows with the API endpoints
A troubleshooting guide for when things didn't go as expected
These guides took partner developers from no context about the Reseller API to a working integration with little to no support from Squarespace engineers. Squarespace engineers and testers were also using the guides to better understand and support the API – something I didn’t anticipate when collaborating to write them.
Trust is Earned Before Commitment
Squarespace completed its migration of Google Domains in late 2024, and a few months later, the first non-Google reseller agreement was signed. It happened because the Reseller API became easier to understand, easier to evaluate, and easier to trust.
That trust was earned through every piece of content a potential partner could read:
Initial business emails or chats summarizing the API
A glossary to align on industry and technical terms
Endpoint guides that showed what the API did, what it expected, and how it responded
Contextual guides that explained how reselling flows would work within their own products
Answers from Squarespace support
Because internal teams were aligned on how the API behaved, what Business Development described in meetings matched what a partner developer found when they tested it and, ultimately, Business Development confirmed this had a real impact on the partner's decision-making process.
Clarity, alignment, and education across an API's content give potential partners what they need to evaluate it. This brings me back to my initial question: what happens when you improve every piece of content for potential partners? At Squarespace, it led to our first non-Google reseller agreement, not because one agreement proves it universally, but because the documentation gave potential partners something essential: a clear picture of what they were saying yes to – and that clarity matters to AI agents as well. LLMs benefit from robust documentation to give more useful answers, especially as their contexts grow ever larger.
