Is API Documentation Marketing?
The parallel between the 4Ps marketing framework and API documentation
To most people, marketing is associated with selling things. Most developers, in particular, see marketing as something that tries to convince them to use a new product. However, when done right, API documentation can borrow elements that are part of marketing.
This article is brought to you with the help of our supporter, Scalar.
Scalar is a suite of powerful & customizable developer tools to help you at all stages of API development. Create beautiful API Documentation in a notion-like editing experience.
Traditionally speaking, marketing is a tool that promotes a product, service, or idea to a specific group of people. Marketing has the primary goal of aligning the needs of an audience with the ones of a business. And, in the process, transforming the people it targets into customers.
As a discipline, marketing has evolved and there are many frameworks to choose from. One popular framework that was created in the 1950s is the 4Ps. I find the 4Ps relevant for our comparison with API documentation because it touches on similar topics. These are the four Ps:
Product: Whatever product, service, or idea a business has to meet the needs of a group of potential customers.
Price: The strategy of deciding how to price the product to its customers.
Place: Selecting the distribution channels and the placement of the product so it attracts its potential customers.
Promotion: The communication tactics to inform potential customers about the product and its benefits.
The first topic involves making sure the product aligns with the needs of its potential users. Think of activities related to designing the product, deciding what features to build, how to brand it, and how to present it to users.
Pricing a product has to do with identifying the benefits users get (the perceived value), the costs of producing it, and what the competition is doing.
Selecting the right placement for the product involves understanding where the target audience will want to consume the product. Then it requires setting up the processes to deliver the product to those locations.
Finally, promoting the product is all about evangelizing it to the target audience, showing what its benefits are, and eventually selling it.
Are you seeing a parallel between marketing and API documentation yet? I think I am. Let's see.
The product is, obviously, the API. Its documentation has everything to do with presenting the API to its potential users. As I wrote before, the five elements of good API documentation focus on how to present the API to potential users.
While API documentation doesn't usually focus on pricing there are cases where sharing this information is valuable. For example, OpenAI has a section of its platform documentation dedicated to estimating costs. Stripe also shares pricing information on their documentation. Twilio even offers API operations to retrieve pricing information. Even though the pricing strategy has already been decided, you should use the documentation to show users the cost of consuming the API.
Placement, in the case of APIs, has to do with the choice of architectural style and the choice of technology. Architectural styles are often translated into API references following one or more specifications like OpenAPI and AsyncAPI. The choice of technology usually has to do with the SDKs and programming languages you decide to support. As I pointed out before, both elements are mandatory for a good API tutorial. And tutorials are one of the pieces of good API documentation.
So, it looks like API documentation is a form of marketing. It's not traditional marketing but more like one directed at a very specific technical audience. An audience that knows what they want and is very knowledgeable about certain technologies.
The goal of documentation is to help a target audience engage with the API as quickly and easily as possible. By aligning the needs of consumers—using their preferred programming languages and offering SDKs—with the business objectives, documentation is a marketing tool you can use to drive results.