How we ensure your documentation is ready for humans and AI tools
Over recent years, our customers have become increasingly aware that their technical content needs to be able to be found, accessed and parsed by AI tools, as well as human readers. AI-readiness involves optimising for AI tools to be able to find your content, read it, and interpret the information in it easily and confidently enough to cite the page in a response. It also ensures the content remains usable for humans.
Many tools
With the multitude of AI tools available, you’ve got no control over the AI tool that external readers will be using. You need your content to be optimised for all tools.
Being authoritative
Your content needs to be the authoritative source on your products; otherwise, on-platform users risk being misinformed by old or third-party information.
The same, but different
Although AI tools and humans are approaching the content in different ways, improvements for one will mostly help the other.
It has already happened
AI is here, and it has changed how people interact with technical documentation. If you haven’t factored this into your docs, you are already behind.
How we ensure AI-readiness for your documentation
What AI-readiness looks like in reality can be different depending on the content. AI-readiness is usually just one consideration when we’re improving a customer’s technical documentation. Below are some key best practices we recommend, along with an example of how 3di applied them to Open Robotics’ ROS documentation site.
Metadata (in page headers)
- Metadata is machine-readable, which enables a fast initial check for page relevance.
- Well-used metadata can also add to AI confidence in an article’s content (as long as the metadata matches the rest of the article).
Organise around subject-matter
- Organising content lists around system functionality establishes a clear, authoritative view of the system, particularly if file paths and metadata also reflect the same patterns.
- The organisation also establishes relationships between parts of the content.
Clear purpose and scope for article
- A good title reveals scope and purpose, without the need to process the full detail.
- The introductory description sets clear expectations, to support decision-making about relevance.
- Matching metadata, titles, article description and other content builds AI confidence in a site’s contents.
- Keeping an article focused on a single content type makes it easier for AI to interpret the article and cite it in responses.
Meaningful headings and article structure
- Semantic markup (Heading 1, Heading 2…) indicates clear structure and clarifies how content in an article is organised.
- Within the body of the content, meaningful headings make it easy to identify pieces of information in the article, making AI more likely to cite it in responses.
- Relationships between headings support understanding of relationships between pieces of information.
Clear, straightforward language
- Clarity makes it easy to interpret content.
- Ambiguity is reduced by avoiding complex syntax and jargon, resulting in fewer errors in AI responses.
- Clear, positive statements – rather than wordy explanations – improve the authority of the content in an article.
Any questions about AI-ready technical documentation?
Consistent terminology and facts
- Consistency boosts how AI perceives the authority of the content.
- More consistent content enables more accurate, definitive answers.
Meaningful structures within the content
- Properly marked-up structures such as tables and lists make it easy for AI tools to interpret content and extract answers from it.
- Numbered lists indicate a sequence of steps, table headings provide labels for pieces of information, code examples indicate samples to provide in answers.
Links to related content
- Links encourage AI indexing to find articles deep in the site’s structure. In this example, the links connect information about what’s possible directly to the package for enabling it. This ultimately also supports code-generation capability.
- Links into a page contribute to a page’s authority, which boosts AI confidence to cite the content in responses.
Questions and answers
- FAQ structures are often prioritised in AI information retrieval, as they make it easy for AI tools to find relevant answers and cite the page.
- In this example, the questions are generated by using AI search to query sources such as discussion forums and support sites.
- As well as dedicated FAQs, Q&A is also supported by starting all sections with clear statements about the subject, followed by supporting detail to provide depth.
Graphics and images
- Our example article doesn’t include images, but when visuals are needed, they need to be described with text, captions or alt text.
- AI tools generally don’t process images currently, so a clear description enables identifying relevance to responses.
Any questions about AI-ready technical documentation?
Our process for getting your content AI-ready
We’ve been helping companies around the world ensure their content is AI-ready, and we have a proven process that we can tailor to your individual needs. We make it as simple as possible for you – no matter how complex your product or content, or how tight your deadline is. Here is a brief overview of our process.
Initial request
We understand what you want to achieve, agree on a commercial plan, and assign suitably skilled 3di technical writers and content tools developers.
Scoping
We assess your current content and what you need to communicate. We create a detailed AI-readiness plan for you to review.
Content creation
We migrate, enhance or create your content – automating what we can. You provide some input and check you are happy with early prototypes.
Delivery
We complete the technical content and fine-tune the final formats for publishing. Once published, we can continue to provide support and updates as needed.
Our AI-tool stack
At 3di, we have spent 20+ years getting the best from industry-leading content tools. We’ve applied that experience and invested in our own in-house team of content tools developers, who create innovative tools to get the best from LLM-based GenAI, without compromising our clients’ data confidentiality and security.
We now deploy a suite of AI-enabled tools, which we use alongside industry-leading content tools to create your technical documentation. Our unique technology ecosystem enables us to deliver accurate, timely technical documentation that is optimised for AI search, ready for translation and localization, and more importantly, perfect for your end-users.
Case studies
Infomir – creating an information portal
Find out how 3di helped Infomir by creating an information portal to manage their product documentation.
Related posts
5 steps to create AI-ready documentation
5 steps you can take to make your technical docs easier for AI to discover…
How to achieve AI-ready technical documentation
We cover what AI-ready documentation is, and how you can achieve it
A real-life scenario: We’ve been told to find ways to use AI for our docs
Here, we’ll discuss some of the pitfalls of integrating AI into your docs strategy.