As a technical writer, my role involves more than just writing. In fact, writing is often the last phase in the process. A technical writer has to wear many hats to ensure that the final documentation product is accurate and provides real value for its intended audience.

Research (and lots of it) is a key activity, along with interviewing stakeholders and taking a hands-on approach to test the completeness, conciseness and accuracy of the documentation. 

Working for a software consultancy means collaborating in interdisciplinary teams with customers who have very different tech stacks, needs, budgets and goals. When it comes to role expectations, project assignments can sometimes feel like a game of Russian roulette. You never quite know what challenges you will face next.

In this context, AI has become a powerful tool. It helps us speed up research, uncover insights, automate repetitive tasks and take a more active role in shaping the solutions we document.

In short, AI enhances our skills and allows us to focus on more strategic work.

Project at a glance:The Challenge: Assessing dozens of non-compliant API definition files.The Solution: Building a custom Python script with Gemini to process validation data.The Result: Saved 20 hours of manual data entry and delivered clear compliance steps.Tool Stack: OpenAPI Specification, Redocly CLI, Python, Google Gemini.

The Challenge: Assessing Existing API Documentation

While creating API documentation is a core part of a technical writer’s skillset, assessing existing API documentation is a different story altogether. I was part of a five-person technical writing team on a project for a customer selling a microservices-based software-as-a-service (SaaS).

Our first assigned task was to evaluate their existing API documentation, which proved challenging due to a few key factors:

• Dozens of API definition files based on different versions of the OpenAPI specification.
• Each development team created its own definition files without standardizing the use of API code generators (which typically require compliant files).
• A lack of consistency in how development teams populated metadata fields, alongside missing naming conventions for required fields. 

Each API definition file was hundreds of lines long. Manually reviewing all of them to identify patterns and gaps would have taken us months, on top of the time we needed to familiarize ourselves with the latest version of the OpenAPI specification. We knew we had to implement automation into the review process.

The Research: API Validation Tools

Our final deliverable needed to include both qualitative and quantitative assessments. We had several questions:

• How many files were valid according to the OpenAPI schema?
• How many errors did each file have?
• What changes were necessary to achieve compliance and consistency?

Then we found Redocly CLI. This tool enabled us to benchmark the API definition files against the latest OpenAPI specification.

The Problem: Analyzing Validation Results

Redocly CLI’s validation feature outputs a list of errors, with their descriptions and severity levels based on the latest OpenAPI specification.

Running this validation across all files saved us a massive amount of time, but it also left us with a large chunk of raw data to analyze before we could craft a meaningful report. Redocly CLI offers various output formatting options, including Markdown tables.

We chose to redirect the terminal output into Markdown files. However, having a set of Markdown files was just another intermediate step. We needed a friendlier format to filter all the data. 

The Solution: Using Gemini to Create an Automation Script 

Because the customer prohibited feeding any sensitive data to Large Language Models, our workaround was to use AI to build a local automation script.

We determined that the path of least resistance was transforming the Markdown tables into Comma Separated Values (CSV) files, which could then be imported into a spreadsheet for data filtering.

The first prompt we used: “Create a Python script that transforms a Markdown table inside a Markdown file to a CSV file. The script must take the Markdown file as an input parameter and generate a CSV file with the same name.”

Through iterative prompting, we tested each script Gemini provided. After a few rounds, we added extra features like command-line arguments and batch-processing capabilities.

The Impact: Speed, Scale and Actionable Recommendations

In less than an hour, we were filtering the data in a spreadsheet, organizing it by definition file, error type and severity. We gained insights into the most common errors, allowing us to start crafting a report with recommendations for the development teams to address their non-compliant files. 

On the qualitative side, we used Gemini to query the OpenAPI specification, fact-checking the outputs against the official documentation. As a result, we were able to suggest best engineering practices, such as utilizing the components object and references, to avoid repetition and achieve more compact API definition files.

Deploying AI in this targeted way saved us around 20 hours of manual work, eliminating the need to copy, paste and format terminal data in a spreadsheet by hand.

Conclusion: The Missing Piece

In the end, AI didn’t magically rewrite the customer’s API documentation or independently assess their architecture. It wasn’t the entire solution.

But by acting as a powerful assistant to handle the tedious data processing, Gemini became an essential part of it. It freed our team to do what we actually do best: analyze the information, craft strategic recommendations and deliver real value to the customer.