Let's talk about AI #3: AI-powered solutions for real-world problems

This is the last article in the series, and it answers a practical question: where does AI actually save you time? We will look at technical writing, marketing, organizing your work, creating graphics, and a few more tasks. To keep it concrete, we will walk through a real project instead of listing abstract benefits.

Building and running developer portals is a big part of what we do at DX Heroes. Every project comes with its own demands, because every client wants something slightly different. Some clients want the visual side finished first. Others care most about deep, accurate technical documentation. Both paths take a similar amount of work and both matter equally in the end.

The work usually rests on three people: a technical analyst, a technical writer, and a programmer. So where does AI fit in? Let's find out.

Every developer portal sits on top of an API specification. That spec lets anyone with the right permissions use the company's services. Around it you build documentation and usage guides so the end user knows how to call those services. From experience we already know what to create to keep things simple for the people who read it.

Picture a common starting point: a client runs an outdated API specification with thin documentation and weak visuals for the portal. Our work begins here, and we split it into phases.

The first step is to convert the existing specification to the OpenAPI 3.0 Specification (OAS), if that has not happened yet. This matters for a few reasons.

First, technology moves fast. The older Blueprint format no longer keeps up with current standards, while OAS lets you add new features more easily. Second, OAS is the industry standard. It guarantees compatibility, smooth collaboration, and comes with a large set of established best practices. Third, OAS gives you a stronger framework for describing your API, which leads to faster integrations, fewer bugs, and more interest from end users.

The next step is to fix the problems that show up. As with anything, an automated migration rarely runs perfectly. Errors creep in, and you still need to validate the result by hand. Several tools help here, and my favorite is Spectral. Spectral reads the whole specification and flags every error and warning. Your OAS is a mirror of the services you offer, so make sure it reflects the real state of your product without flaws.

Now AI comes in. This is the part where you make sure your customers understand everything about the services you offer: descriptions, examples, guides, high-level explanations, and a lot more. Language models like Jasper or ChatGPT help you write all of it. The trick is to train the model on your project before you ask it for technical documentation.

I do it in a few steps, and I can recommend the same to you:

Once you go through these steps, it becomes easy to get ChatGPT to generate a clean description for a given set of parameters. That saves a lot of time, and you do not have to stop there.

We have heard a lot of positive feedback about audiovisual components that help users understand a product and how to use it. Accompanying graphics or short video tutorials work best. Here is another point for AI. You can now create video tutorials with bots that speak more than 30 languages and dialects, which removes almost all the hardware and language barriers. The bonus: you already hold product knowledge from your earlier conversation with a trained GPT, so you can reuse it directly to write the narration.

The final step is to make your work public. Marketing carries real weight, so make sure your customers hear the news. AI helps here too. Try Rapide.ly, a handy tool for your marketing in general and for planning how to create and announce news.

I hope this gives you a clear picture of how AI fits into the world of OAS and technical documentation. Do you know a tool we did not mention? Let us know.

You might also be interested in: