API products as a driver of business and IT convergence

There are two major challenges with applying the concept of Productization to APIs:

1. It is not a natural concept for most technologists and delivery prioritization is generally focused on getting things out the door as fast as possible.

2. Marketing & product teams live and breathe productization concepts but APIs are not well understood. These teams are highly likely to defer to technical teams.

When combined, productization of APIs is not going to happen without a concerted effort and leadership support. API programs that do not successfully adopt a product mindset will dramatically underperform.

So how can you overcome these challenges to achieve a successful transformation?

Overcoming Challenge #1 – Perceived Delivery Agility vs. Productization:

API productization requires deliberate focus on a few essential practices- basic documentation to enable consumer discovery & self-service is at the core. Yet many Agile teams have twisted the code over documentation principle and adopted an all documentation is waste philosophy. But why?

• There is a direct correlation between skipping documentation and getting the current sprint delivered faster.
• There is a long IT history of 20+ page documents describing system interfaces which were seldom (if ever) read.
• There is also a long history of organizations eliminating tech writer roles. While I don’t support having a separate tech writer position, it has sent the message that most companies don’t care about documentation.
• Documentation is almost never a measure of individual or team performance tied to personal financial incentives (bonuses, raises, etc.).

Most of the considerations above are based on false assumptions or simply don’t hold up over time or in today’s world.

Reality check:

1. Current sprint delivery can be accelerated by skipping documentation, but this tech debt builds up quickly. For example:

Developers spending time onboarding new resources…

…or educating operational team members…

…or supporting others teams trying to integrate with them…

…are not delivering new business value!

This reality is frequently hidden by velocity numbers (e.g. our team velocity is consistently [n] so we are doing really well). Since velocity is a measure of typical team throughput over time… support time pushes this number down. How much higher could your velocity be without waste due to unneeded support?

2. Heavy documents have proven to add little to no value inside most companies. Retail product documentation has already gone through this shift. 20 page user manuals have been replaced with trifold Quickstart guides describing intuitive products. This same paradigm shift should be applied when productizing APIs.

Make your APIs intuitive and create concise but useful docs that simply point API consumers in the right direction.

So… how do we convince people and overcome this first challenge?

Initially, establish your API Lifecycle completely separate from your delivery organization and create team & individual performance measures that drive productization outcomes. This does a few things:

1. It allows Conway’s Law to work toward your API practice goals, not against them.

2. It allows you to control the flow of new APIs into production while ensuring productization practices are established and followed.

3. It allows you to prove the value to both leadership & delivery teams… people will generally need to live it to believe & rely upon it.

4. It allows you to largely isolate your API Lifecycle from some of the delivery pressure.

Once you have a working, proven API Lifecycle and effective risk and insight-based oversight practice in place, you can shift toward federating API Delivery back out to delivery teams.