4 Signs it’s Time to Expand Your API Docs

4 Signs it’s Time to Expand Your API Docs

Olivia Ramirez 8 min
By Olivia Ramirez

You’ve been building lots of integrations, and your agency partners are excited to put them to use for your mutual clients. Each client needs custom functionalities and features that the existing integration simply doesn’t satisfy without a little extra development work here and there. But soon, one back and forth with your agency devs to satisfy a client’s bespoke needs turns into twenty, and twenty clients turn into forty, and… “Ahhhh!” *Door slams shut* (Did your dev just run away with their hands flailing?) 

If this sounds like you, it might be time to create API documentation — the first step to empowering your partners to build integrations with your product themselves while freeing your own team for more impactful tasks.

We spoke with Brian Jambor, Head of Partnerships at Nacelle, to hear why their team shifted gears to expand their API documentation on top of integration development. 

“Oftentimes partnership leaders focus a lot on the integrations and focus less on documenting the best ways to [leverage] them with examples,” says Jambor. 

Below, you’ll find four questions you should ask yourself when deciding if your company should prioritize API documentation. 

#1 Your Integration Users Tend to Require Custom Development Work

The more complex your product is, the more likely you’re going to need room for flexibility. For example: If your product is a customer relationship management (CRM) tool, it could take more than a year to implement depending on factors like: 

Take Nacelle, a composable headless commerce company that enables e-commerce brands to customize the front-end shopping experience for their customers (think: faster load times, improved user experience, better conversion rates) while leveraging the back-end store management system of their choice (like Shopify Plus). A high level of customization is a huge selling point for Nacelle’s customers. 

Prior to expanding API documentation, Nacelle’s developers were working on two types of integrations:

Type #1: Integrations that pulled e-commerce and content data into Nacelle to accelerate the development of the front-end shopping experience. Nacelle was working with tech partners to pull e-commerce and content data into Nacelle’s data stream so clients could utilize that data when building their customized front-end shopping experience. Take Shopify, for example. Clients who use Nacelle’s integration with Shopify and Contentful can pull rich data from both Shopify and Contentful into their front-end shopping experience easily through a single API which accelerates the development of the front-end storefront.

Type #2: Integrations that enabled a high level of customization for their e-commerce clients’ front-end shopping experience. Nacelle’s developers worked with agencies to integrate third party applications into their mutual e-commerce clients’ front-end shopping experience (which is completely outside of the Nacelle product). 

Both types of integrations are critical to the success of Nacelle’s clients; however, the integrations that fell into type #2 required a high level of time and resources from Nacelle’s developers. Nacelle’s team determined that the integration development for type #2 would be better-suited for the agency developers to manage, since these integrations required a high level of individualized customization for each client. Hence, they decided to expand API documentation.

Brian Jambor and the Nacelle team decided to expand API documentation in order to help their agency partners build out custom functionality for each client. They made this decision because:

  1. Their agency partners were coding from scratch since their mutual customers needed custom functionality on top of existing Nacelle functionality. 
  2. Nacelle’s engineering team needed to build and manage each integration and each variant per customer, an inefficient use of the team’s time and resources. 

API documentation on Nacelle.com

#2 The Rate of Integration Requests Outpaces Your Ability to Build Them Internally

How big is your integrations team? Do you have developers dedicated to building integrations, or do they balance their responsibilities between the product roadmap and the integration roadmap? The maturity of your integrations team plays a role in whether you should focus on documentation or integration building. If you don’t have the headcount or capacity to build and maintain a large number of integrations, you’ll need to determine if increasing those resources (translation: increasing budget) is worth the end result. If your integrations will require a large amount of customization, it might be time to focus on expanding documentation that can help your partners create the functionalities your joint customers need.

“The maintenance of all of those integrations became a very heavy lift,” says Jambor. “There was a fork in the road point of, ‘Okay, do we want to allocate a significant team and resources to maintain a bunch of these front-end integrations, and the more integrations we have if we develop them the more resources we have to throw at this, and what’s the longtail value of this?”

Consider the dollar amount of hiring more headcount to compensate for each wave of new integrations. In Nacelle’s case, their devs worked hand in hand with their agencies’ developers to understand the scope of their mutual client’s needs — essentially working with the agency from project ideation to delivery. That’s a lot of time and resources! 

#3 You Use a Sales-Led Growth Strategy

Companies that focus on product-led growth onboard new users on a free tier to see the value of their product before graduating them to a paid tier. The more your product fits into the user’s tech stack, the more value they’ll see. The goal? “Stickiness.”

(Check out how we launched our first tech ecosystem with more than 30 integrations in six months.)

Jambor says companies that have the following characteristics may want to prioritize building more integrations rather than creating or expanding existing documentation: 

  • Product-led growth companies that graduate users from free plans to paid plans 
  • Small to mid-size companies that prioritize “stickiness” by fitting into customers’ tech stacks with the other tools they use most 
  • Products that have “shadow IT” users. For instance: someone uses RocketReach to gather email addresses from LinkedIn profiles while prospecting. The user’s IT team is not aware that they are leveraging this tool — hence the shadow! In this case, RocketReach is generating more users because they have an integration with LinkedIn.

Nacelle uses a sales-led strategy. Its customers want to make their front-end storefront their own from the get go, which often requires talking to a services rep on the agency side to bring their vision to life. There’s no need to start using a free version of the product right away (like in product-led growth) before using it in production. This high need for custom developed storefronts elicits a high demand for development. Documentation makes that easy for Nacelle’s agency partners to fulfill. 

#4 Your Agency Partners Typically Implement Your Product for Your Mutual Clients

If your professional services team implements the product for your customers, then there won’t be a big need for documentation for others to develop on your behalf. If you work with agency or system integrator (SI) partners to implement your product for the client, then there may be a need for documentation. 

If you work with marketing and development agencies that have in-house developers, have a conversation with your partner to set expectations about: 

  • The kind of documentation their development team needs to manage the work successfully for your shared clients 
  • The time commitment needed from your partner’s development team and how that translates to any changes in compensation and contracts they have with you 

Jambor says building the integrations that fell into “type #2” internally put limitations ons Nacelle’s agency and SI partners who were trying to support clients with bespoke needs. 

“They wanted expanded documentation,” says Jambor. “They wanted to create the connections themselves as part of these front-end custom-built sites more so than they wanted something that was completely constrained in a box that didn’t allow them the flexibility.”


Are you considering making big changes to your partner program. Our 14-question tech ecosystem maturity diagnostic can help you identify where your partner program has room for improvement and how to advance to “Supernode” status. Take the diagnostic, and receive custom-tailored next steps. Plus, learn how to level up your integrations team and other criteria from the diagnostic on our blog.

Olivia Ramirez 8 min

4 Signs it’s Time to Expand Your API Docs

If your customers require bespoke functionalities and features from your product, it could be time to create API documentation.

You Might Also Like


This is a test comment.


This is a longer test comment to see how this looks if the person decides to ramble a bit. So they're rambling and rambling and then they even lorem ipsum.