Skip to main content

3 ideas on AI readiness, the role of APIs and developer portals in generative AI systems

CEO, Co-Founder
Jun 05, 2023

How can we prepare our organizations and information systems so that in the future we will be able to safely and effectively use AI in our organizations? How can we improve our AI readiness?

AI and Large Language Models (LLMs) have created the mother of all hype cycles. That is why we weren’t sure if the world needed another hot take on AI. But most of the content out there, is either talking about new things AI is doing this week, how big the risk is for some AI catastrophe, jobs that will be lost or created because of AI, and ways you can use AI to augment your work output.

After we’ve all built a ChatGPT bot or plugin to do X, and have marveled at how close it sometimes comes at doing a human’s job, what can technical writers and API product/program owners do to anticipate the changes AI will trigger? What is it that we can do to adapt?

So far there has been little talk about AI readiness, and what infrastructure organizations need to have in place to utilize AI effectively and safely from an information perspective. In this blogpost we explore a couple of ways how technical developer documentation and APIs could become training sources, and/or authoritative information sources for interfaces that use LLMs or similar generative AI systems.

This article was inspired by Stephen Wolfram’s publications including his blogpost “What Is ChatGPT Doing … and Why Does It Work?” and is based on my personal observations, it is forward looking and of a speculative nature. So if you find yourself strongly agreeing or disagreeing with any part of this article, I would love to hear so in the comments on this introduction post on Linkedin.

Generative versus authoritative

Have you ever wondered what the difference is between the information output from a computer and a human? I’ve thought a lot about this as part of my fascination with complexity, and I’ve started suspecting that engineered systems like computers are so different because they are an attempt at making a deterministic system: as a software developer, you don’t want to be surprised by the software you write (any unexpected behavior is typically seen as a bug).

This differs from complex adaptive (biological) systems, where creativity and emergent behavior are expected and appreciated. LLMs and generative AI are designed to exhibit the emergent behavior of biological systems. They are getting better and better at sounding like a human, and that is what makes them so impressive.

Bi-modal information retrieval and computation

The problem with generative content, however, is that no matter if it comes from a human or a machine, it is not always factual. Since the rise of literacy and even more so since the adoption of computing, we have relied on technological artifacts such as books, reports, and databases to verify information output from humans, whether they are experts or novices. As human cognition has become more and more entangled with the machines we created, we have started to rely more and more on technology to help us to be factual. 

Even if you ask an expert a question, they will give a first approximate answer, and when asked for certainty, either look up the answer in an information retrieval system, or calculate it with some sort of computing technology (e.g. pen and paper, abacus, calculator, mobile phone, PC). We could say that we are using a(n at least) bi-modal information system with:

  • a first generative mode: that is there to generate ideas on how to approach a problem, and to get an approximate answer to a question,
  • a second authoritative mode: that attempts to be factual and exact, and that gives definitive answers.

Given the difference between these information generation, retrieval, and computation modes, I think it is really important that we don’t confuse generative information processing with authoritative information processing. The answer might come from a computer which based on our prior experiences we might expect to be factual, but with LLMs that is not necessarily the case. We can attempt to train AI models - just like we train human experts - to make fewer mistakes, but LLM systems are not designed to be factual, they are designed to sound human. That is why I believe we need to start consciously engaging in a multi-modal fashion with our computing devices.

1. Platform APIs to interact with the universal interface

One of the most impressive AI demos I have seen in the past weeks, was of an AI demo that independently figured out how to make an API call. This brings the future in which we all have personal AI agents that retrieve information for us so much closer.

It is not hard to imagine how similar technology could become a personalized universal interface that understands our context, and that can interact with the world around us. When generative systems can learn to submit inquiries from authoritative systems, they become like humans capable of using multi-modal information retrieval & computation. 

This is why I believe that the best thing companies can do to get ready for interacting with AI agents both inside and outside their organization is to define a complete set of APIs, that help an organization provide authoritative answers to their employees and partners across all of its functional domains.

2. Documentation as a high-quality training source

In a blogpost about a leaked internal document from researchers at Google Dylan Patel and Afzal Ahmad discussed how Open Source AI has a good chance to outcompete both Google and OpenAI, the current leaders in the AI race. Researchers have found that data quality scales better than data size: that projects can save a lot of time and money by training on small, highly curated datasets.

This suggests there is some flexibility in data scaling laws. The existence of such datasets follows from the line of thinking in Data Doesn't Do What You Think, and they are rapidly becoming the standard way to do training outside Google. These datasets are built using synthetic methods (e.g. filtering the best responses from an existing model) and scavenging from other projects, neither of which is dominant at Google. Fortunately, these high quality datasets are open source, so they are free to use.

Practically I believe that this means that the quality of the data being used to train AI matters a lot. It is the old garbage in, garbage out premise. While unstructured chatter will have a role in training LLMs, I also believe that up-to-date authoritative documentation will become more and more important as training sources for organizations. While conversational content (e.g. support chats, emails, instant messaging logs) can help to make better generative content, it also risks lagging behind any changes that have happened since the content was created. Legacy conversations might have out-of-date information, and I suspect that organizations will have to regularly retrain their LLMs to keep generated content up-to-date.

If we are expecting to train AI on the ongoing conversations in an organization we also need to watch out that this doesn’t include unsupervised content that is partially or fully generated by AI. Otherwise you can imagine an out-of-control feedback loop that keeps on amplifying incorrect information, until it overwhelms the system. To prevent this from happening, we will need to verify the quality of information. So I believe technical writers and editors might be at the cusp of a golden age.

For this same reason I believe that (developer) documentation will become even more important: as both a source of authoritative and up-to-date information about APIs, and as a high-quality training source for AI. Obviously I am biased, but I believe that developer portals, as a tool to deliberately manage the publication of both business and developer documentation, will become even more important. This is in contrast to what Abhinav Asthana, the CEO of Postman projects in his article on “Generative AI and the impact on APIs and software development”. But I am convinced this is the case, otherwise we risk repeating the same mistakes companies made with the roll-out of Confluence wikis: documentation needs to be curated and maintained, “we don’t need a docs team because the community will write the docs” is a dangerous belief that instead of saving costs, has in many organizations increased costs through countless hours of frustration and wasted effort (I really need to write a blogpost about this).

3. Interfaces to constrain asymmetrical information requests

As the use of AI becomes more widespread, it will increase the demands on human attention even further. That is why I expect that soon humans will be even less able to deal with all incoming information requests, both in their personal and professional lives. Attention will become an even more scarce resource that will need to be protected.

As the attention arms race intensifies, we will eventually need to resort to AI agents to manage the chatter, but it is not yet clear how those intelligent agents will function and how fast they will mature. So as the noise intensifies, we will need other coping mechanisms because living systems can’t seal themselves off from their environments.

Biological systems utilize the pattern of selective boundaries and “enabling constraints” to deal with the complex environments they live in. They use interfaces that are designed to amplify information that is important for them, “differences that make a difference”. I believe external APIs and low/no-code interfaces will evolve to fulfill a similar function in future organizations. In anticipation of the AI informational barrage, organizations can start deliberately mapping out their interfaces with the world. In the past I have talked about interface portals: developer portals that go beyond Application Programming Interfaces, to help companies deliberately declare their interfaces to the world. I think this will become essential, especially for enterprise companies that have a large and complex surface through which they interact with the world.

Where possible these interfaces also need to be self-service, and for interfaces that are not self-service, the authorization process needs to be streamlined, to make sure information requests can be processed at scale. This is one of the key roles of developer portals.

AI readiness

So what can you do to prepare your organization for the coming AI roll-out? I believe you could do the following four things:

  • Curate a set of platform APIs that employees and partners will be able to use through AI enabled applications and a possible future universal interface.
  • Improve processes to create and maintain authoritative documentation: wiki solutions like Confluence have been shown to suffer from information rot when well-meaning employees contribute content that is not maintained. If that content is used to train AI, it will further deteriorate the output of the system.
  • Get a complete set of APIs that act as enabling constraints on communication between teams inside of your organization, and between your organization and your partners and customers.
  • Develop processes and systems that enable and secure self-service interface requests. As AI will exponentially scale information requests, your organization needs to step away from manual access approvals.

Have feelings or thoughts about anything I wrote? Please join the conversation on the Linkedin post I’ve used to announce this article. If you are thinking about AI readiness and would like to explore how your developer portals could help your organization be ready to adapt, I would be happy to have a conversation.

Kristof Van Tomme is an open source strategist and architect. He is the CEO and co-founder of Pronovix. He’s got a degree in bioengineering and is a regular speaker at conferences in the API, developer relations, and technical writing communities. He is the host of the Developer Success & the Business of APIs and the API Resilience podcasts.


Articles on devportals, DX and API docs, event recaps, webinars, and more. Sign up to be up to date with the latest trends and best practices.