Let's talk about AI: #3 AI-Powered Solutions for Real-World Challenges

The last piece in this series will examine how to use AI technologies to optimize performance on a variety of tasks, including technical writing, marketing, organizing your work, creating graphics, and much more. Let's look at it together.

Let's begin with a real-world use case

The creation and management of developer portals is a critical component of what we do at DX Heroes. This presents a wide range of challenges that are directly related to the client's needs. While some clients prioritize completing the visual part first, others focus on obtaining the most detailed technical documentation possible. At the end of the day, each approach is comparably crucial and requires similar amounts of work.

The required skill set revolves around the abilities of three key project participants: a technical analyst, technical writer, and a programmer. But how does AI fit into this whole story? Let's see.

Creating a developer portal with the help of AI

At the core of every developer portal is an API specification that allows anyone with valid permission to use the company's services. On top of that, you should develop a comprehensive set of documentation and specifications for using API services. We already know what needs to be created, based on our experience, to make it as simple as possible for end users. Consider the following scenario: A customer is using an outdated version of the API specification with little documentation or insufficient visuals for the dev portal. This is where our work, which is divided into phases, begins:

Modernize 

The priority for the first step is to convert the existing solution to the OpeAPI 3.0 Specification (OAS) format if it's not done yet. This convention is important for several reasons. The first reason is that technological advancements are moving forward very quickly, and for example, the Blueprint format no longer keeps pace with existing technology standards, while OAS offers the ability to integrate new features more easily and quickly. The second reason is that OAS is already regarded as an industry standard that ensures compatibility, one-door collaboration, and provides countless best practices. As a last point, I would like to mention that OAS provides more robust frameworks for API description, which leads to faster integrations, reduces bugs, and attracts more attention from end users.

Tip for you: My favorite product to convert any kind of API specification  is APIMatic – https://www.apimatic.io/solution/transformer

Resolve 

The next step is to resolve any problems that may arise. Like everything in life, nothing always goes perfect, even with an automated migration. All sorts of errors can occur, and manual validation is still required. There are various tools for this; my favorite is Spectral. Spectral basically takes the entire specification and highlights areas where there are errors or warnings. Your OAS is a reflection of the services you offer, so it's very important to ensure that it’s a flawless reflection of the real life state of your product.

Tip for you: I can more than recommend Spectral for real time validition of your OAS – https://github.com/stoplightio/spectral 

Explain 

Now AI finally comes in. This is the part of the process where you need to make sure your customers know everything they need to know about the services you offer. We're talking about different descriptions, examples, guides, high-level explanations, and a lot more. This is where language models like Jasper or ChatGPT come in. But how? Start training an AI model to help you with technical documentation. 

I personally do it in several steps that I can recommend to you:

1. Illustrate what project you're working on and what is your concrete goal
2. Explain what language format you’d like to use
3. Provide an example of what a parameter description should look like
4. Describe what you expect as the output

If you go through these steps, it is very easy to get to the stage where, e.g., ChatGPT will help you generate a simple description for the given parameters. This saves a lot of time in the end, and there is no need to stop there. 

We've received a lot of positive feedback towards creating audiovisual components that help users understand your product and how to use it. The best way to do this is with accompanying graphics or short-form video tutorials. Here's another strike for AI. Nowadays, you can easily create video tutorials with bots that can speak more than 30 languages and dialects. This eliminates the need for nearly all hardware and language knowledge. The icing on the cake is that you already have stored product knowledge from a conversation with a trained GPT about your product, which you can directly use to generate the narratives.

Tip for you: No need to mention ChatGPT, but check out Jasper and also Synthesia as very helpful tools for this particular step. 

Publish

The final step is to make your work public. Marketing has enormous power, so make sure your customers are aware of the news. But AI can also help here; try Rapide.ly. It's an intriguing tool that can help you with your marketing in general as well as guide you on how to create and communicate news.

Tip for you: Power up you marketing with another AI tool – rapide.ly 

I hope this information helps you understand how AI is used in the world of OAS and technical documentation. Do you know about tools we have not mentioned? Let us know! 

You might also be interested in:
Let's talk about AI: #1 The yin and yang of AI

Let's talk about AI: #2 The Top 5 AI Tools for Technical Writers

Improve API adoption with OpenAPI specification 

Author

Jan Řičica

Technical Analyst & Writer

I handle complete software analysis, from gathering requirements from clients to creating technical documentation.