5 practical actions toward AI-readiness

Technical Writer, DocOps Engineer

Apr 28, 2025

As we explored in Part 1, improving the AI-readiness of your developer portal does not mean rebuilding everything from scratch. A focused, strategic approach can make your content more usable, discoverable, and valuable, both to developers and AI-powered tools. Here's how to start:

1. Apply the Pareto Principle: Prioritize high-impact content

Improving your entire content library can be daunting. Start with the 20% of your content that drives 80% of user interactions and AI value. Focus first on the Minimum Viable Documentation (MVD):

API Reference: Use structured formats like OpenAPI for REST APIs to expose endpoints and schema in a machine-readable way.
Onboarding guides: Break down workflows into clear, step-by-step instructions. Use visual elements with descriptive alt text and consistent internal links.
API overviews: Provide plain-language summaries of API products, focusing on capabilities and business value for non-technical users.

For these critical content types, aim for machine-readable formats such as Markdown and YAML. If your current writing tools create unstructured outputs (e.g., Google Docs, Word), ensure the final content is converted to formats that AI systems can parse reliably.

2. Improve documentation quality with a targeted content audit

Before automating anything, audit your existing content. Assess:

Accuracy and relevance
Usage patterns (via site analytics or support data)
Gaps in structure or clarity

Use this to identify what to improve or rewrite. This supports AI-readiness and elevates the overall developer experience.

You can fill out our self-assessment to gain valuable insights into elevating your user experience and documentation quality.

Start the free assessment »

Also, review your editorial process. Establish writing standards that ensure consistency in tone, terminology, structure, and metadata. These help AI models deliver accurate answers and recommendations.

3. Strengthen content hierarchy and metadata

A strong information architecture is essential for AI to understand your content ecosystem. Focus on:

Consistent and straightforward URL structures to reflect hierarchy and topic groupings.

Bad examples:

```
www.zero-gravity.org/node/32 
```
```
www.zero-gravity.org/bpapi-tutorial 
```

Good examples:

www.zero-gravity.org/apis-for-the-universe

www.zero-gravity.org/api-catalog/best-product-api/tutorial

Parent-child relationships between content types (e.g., concept → tutorial → reference).

Bad examples:

www.zero-gravity.org/best-api-product-reference

www.zero-gravity.org/best-api-product-reference-tutorial

Good examples:

www.zero-gravity.org/api-catalog/best-product-api/api-reference

www.zero-gravity.org/api-catalog/best-product-api/tutorial

Rich metadata including tags, categories, versions, and supported features.

An example from Zero Gravity APIs, which showcases the data and metadata. — *Metadata supports traditional search and enhances user experience, enabling features like faceted filtering.*

Another example of APIs, where data is the name and description, metadata is the category. — An example of providing metadata in a developer portal is organizing APIs into logical categories. Attaching category labels to APIs not only helps AI but also allows filtering. The more APIs there are on the page, the more important it is to define metadata. The example is from Shell Mobility’s developer portal.

This foundation allows AI tools to grasp how topics relate, enabling smarter search, personalization, and recommendation systems.

We discussed earlier how a healthy content hierarchy and consistent metadata also improve human usability. These principles equally benefit machines: a clear win-win.

4. Make content discoverable - Internally and for AI

Well-structured internal- and cross-linking boosts usability and AI comprehension. Use:

Manual linking to connect related topics, API references, and tutorials.
Automated linking tools like Drupal’s SmartLinker AI to scale internal linking consistently.

Good linking not only guides users, it helps AI models understand topical clusters, which improves their ability to retrieve, summarize, and contextualize content correctly.

5. Convert legacy content to structured formats

Legacy documentation often lives in PDFs, Word files, or unstructured HTML. These formats can be expensive for AI to process and difficult to extract meaning from. Here is how to handle them:

HTML to Markdown

As we discussed, AI tools often charge based on the number of tokens processed, and HTML (the traditional structured content format of web pages) adds significant overhead. Markdown is cleaner, cheaper to process, and retains essential structure.

Use tools like Markdownify and llms.txt to convert web content from HTML to Markdown and offer an entry point to AI tools.

*What a human eye can see: a landing page of the Zero Gravity developer portal with a header text, buttons, and card elements showcasing the portal’s benefits*

The HTML source code of the previous image — *The HTML source code that AI sees by default: the message that the landing page is trying to convey is surrounded by information (tags) that is not relevant to the meaning.*

An image that showcases the markdown version — *Markdown version of the page that AI can see after the transformation: The most important structural meanings and the message are well-reached.*

To put the difference into perspective, we calculated the number of tokens in different formats needed to transmit the same information using the GPT-4o & GPT-4o mini Tokenizer:

The original HTML version contains 40 988 characters, which breaks down into 11 184 tokens due to its heavy use of tags and styling elements.
After converting the same content into Markdown (preserving only the essential structure and meaning), the size drops to 6 577 characters and just 1 580 tokens.

Markdown can be 5 to 10 times more token-efficient than HTML, meaning it is significantly cheaper and faster for AI systems to process.

PDF to Markdown

PDFs are notoriously inconsistent, especially with mixed content types. If you have tagged PDFs, prioritize converting those first, as they contain some structural hints.

Tools like Marker (an open-source extractor) can convert PDFs into Markdown. This makes content easier to reuse in AI training, indexing, and content generation.

Let’s take a look at an example text-based but semantically untagged PDF.

An example of a PDF document from Adobe's website — *What the human eye can see: The first page of a 4-page document with the company logo, the documentation title, the version information table, and the first half of the first chapter with an image.*

The same Adobe example in a different format — *The extracted content of the example opened in a browser PDF. Semantic and structural elements are not preserved.*

The image showcases the markdown format of the same content. — The example PDF document was converted into Markdown and opened with a plain text editor. Embedded images are extracted and referred back, basic semantic structures are restored. As the file contains inconsistent artifacts (encoding junk) and layout-dependent cues (visual bullet points), complex structural information would need to be inferred or manually cleaned up for AI use.

After converting the PDF content to Markdown (preserving only the essential structure and meaning), the output contains 5 741 characters and 1 148 tokens. The conversion took 7.5 seconds.

Can an AI-based search engine access external PDF content?

AI-based search engines cannot access external PDF content by default.

AI search engines on your site can only access internal content and uploaded files. If your portal only links to external PDFs, the AI won't know what is inside them, leading to poor search results. Similarly, if your site links to PDFs hosted elsewhere, the AI cannot access them unless it has permission, the PDFs are public and indexable, or your search system crawls and caches them.

The image showcases the previous example in another format. The AI robot has a question mark as it does not understand the content. — *The AI can see the link of the external PDF but can’t extract its content*

So if you rely solely on links to external PDFs, your search engine becomes more like a directory, not a semantic search tool.

What would an AI need to return valuable results from PDFs?

To deliver AI-powered search results for PDFs, the PDFs must be accessible to the search system, well-structured, and associated with relevant metadata.

Best practice

If the content must live externally (e.g., for compliance), then:

Periodically import or sync the key external PDFs into your portal.
Extract and index their content in a structured way.
Present users with summarized or previewed content with the option to open the full PDF.

In summary, conversion is not just about format, it also highlights underlying quality issues. Fixing those will enhance both human and machine experiences.

Bonus: Use AI to enhance content quality

AI can also support content creation and enrichment. In Drupal, for example, AI Automators can perform specific enhancements, like generating alt text for images, improving both accessibility and AI comprehension.

Unlike AI Agents that interpret and respond to user inputs dynamically, Automators apply predictable transformations that ensure your content meets quality and format standards consistently.

Final thoughts on AI-readiness

AI-readiness is not a one-time fix, it is an ongoing content maturity process. Based on our experience, effective content management supports collaboration by accommodating different contributor roles. A robust content management platform, such as Zero Gravity provides non-technical writers with an intuitive environment for creating documentation, while also supporting developers through CI/CD pipeline integration for code-centric workflows. Enabling contributions across roles strengthens collaboration and improves content quality.

We recommend starting with high-value assets, improving their structure and clarity, and converting your legacy content to more machine-friendly formats. As your portal grows, well-governed content will not only support developers more effectively but also unlock the full potential of AI-powered assistance, search, and generation.

The effectiveness of AI features like smart search, contextual help, and automated troubleshooting is affected by the quality of the content on your developer portal. The amount of effort needed to prepare your content for AI depends on how much importance your company has placed on content and documentation.

Organizations that have already invested in creating well-structured, semantically rich, and up-to-date content will find themselves better positioned for AI adoption.

For companies where documentation and content were not a primary focus, there will be a considerable amount of work needed to assess, convert, structure, and enrich their existing legacy content before they can fully leverage the benefits of AI.

Strategies for improving AI-readiness include conducting content audits, improving content hierarchy, and using tools to convert legacy content to more structured formats.

While content strategy may not be the only ingredient in a successful AI journey, with it, you create the conditions for AI to truly enhance the developer experience. From there, data infrastructure, tooling, and cross-functional collaboration can build on this foundation to drive sustainable AI-driven transformation.

Fill out our technology-agnostic assessment, receive actionable insights to enhance user experience and documentation quality.