Integrating API & developer documentation into a company wide developer Hub

How do you build a unified #developer #documentation experience for your whole organisation?

More and more I've been getting this question on introduction calls and strategy discussions with new customers. I see two reasons why this is happening:

1. Documentation islands

I start to suspect that the rapid growth of #Docs_as_Code - a way to write documentation in a code repository like GitHub or GitLab so that it can be managed together with the code a team is writing - might be causing coherence problems on a broader scale.

The problem is not the methodology itself, but a focus of documentation tools and practices at the project level, instead of the broader organisational level.

2. Breakaway API teams

Even though APIs have gained a lot in importance, many executive teams still struggle to understand what they are and how they impact the business. API program owners often struggle to explain them to their management.

This is causing a range of problems:

• API programs are started as the "technology thing all the cool companies do" without a clear integration in the broader business #strategy. Poor coherence with the interests of the company causes a boom and bust style of investment.
• A lack of integration in the broader organisational efforts gives API teams the ability to just do their thing in isolation, building stand-alone developer portals for individual API teams/programs. Creating all kinds of #findability and #discoverability problems.

Developer Hub

Together with my colleague Christoph Weber I'm writing a mini-series that explains how you can start addressing these problems with a (Drupal-based) Developer Documentation Hub that consolidates or republishes documentation from across the organisation. The first article that we just published goes a bit deeper in onto the reasoning why this is important, the second will give a stab at explaining how to solve the problem.

I had a lot of fun rewatching the original "Cat Herders" advertisement from "EDS, an HP Company" and 宜家 's Herding cats parody movie