Open Knowledge Format: What it means for technical documentation

Could technical documentation become the knowledge layer for AI?

This month, Google Cloud has introduced the Open Knowledge Format (OKF). It’s an open specification for packaging organisational knowledge in a form that both people and AI agents can use.

An OKF collection is essentially a directory of Markdown files. Each file contains a small amount of structured metadata in YAML frontmatter, followed by ordinary Markdown content. Documents are connected using standard Markdown links.

What problem is OKF trying to solve?

The answers from AI systems depend on the context available to them.

Inside an organisation, information is often scattered across many different locations. This means an AI assistant needs to assemble its answer from several sources. Each source might differ in the information structure and terminology it uses. The AI system might also need to access different APIs.

OKF proposes a common interchange format for the source information that AI systems use. The idea is information could be exported into a collection of linked, self-describing documents. The goal is to avoid an organisation needing every AI product to understand every documentation platform and data store.

What does an OKF document look like?

Each concept is represented by a Markdown file.

A concept could be almost anything:

• A product
• An API
• A database table
• A business term
• A software component
• A procedure
• A metric
• A troubleshooting topic
• A runbook

At the top of the file, YAML frontmatter provides structured information, such as its type, title, description, tags, associated resources, and a timestamp. The rest of the file is in Markdown.

Example

We used ChatGPT to generate an example of a Help topic that used the OKF standard:

---

type: procedure

title: Reset a customer’s API credentials

description: Steps for replacing compromised API credentials.

tags:

- security

- account-management

timestamp: 2026-06-12T10:00:00Z

---

# Reset a customer’s API credentials


Use this procedure when an API credential has been exposed or is

believed to have been compromised.


## Before you begin


Confirm the identity of the account owner and review the

[credential security policy](../policies/credential-security.md).

A lightweight knowledge graph

The links between documents create a lightweight knowledge graph.

A procedure can link to a product, a product to an API, and an API to its authentication policy.

Progressive disclosure for AI agents

The file structure can also help an AI agent explore the information progressively, rather than loading an entire documentation set into its context window.

Does this sounds familiar?

For many technical writing teams, none of this will feel especially revolutionary.

Markdown, YAML metadata, topic-based authoring, cross-references and content stored in Git repositories are already common in documentation-as-code workflows. And structured authoring systems have also been separating content from presentation for years.

OKF does not replace approaches such as DITA, DocBook, or a component content management system

OKF does not currently offer the sophisticated content models, conditional processing, reuse mechanisms, or publishing controls found in mature documentation systems.

This is because its purpose is different. OKF is intended to be an interchange format for knowledge, particularly knowledge consumed or maintained by AI agents.

OKF does not replace iiRDS

Both OKF and iiRDS (the Intelligent Information Request and Delivery Standard) aim to make information portable, machine-processable, and authoring-tools independent. However, their scope and level of sophistication are different.

The two formats also address different problems:

• iiRDS is designed to help a system select and deliver the right technical information for a particular user, product, and situation.
• OKF is designed to make many forms of organisational knowledge portable and accessible to AI agents as well as people.

They might prove complementary rather than mutually exclusive.

OKF is different to Schema.org

Schema.org is primarily a vocabulary. It is designed to help search engines understand entities and published resources on the Web. It supplies shared types and properties for describing entities such as products, organisations, articles, and procedures.

OKF is primarily a packaging and interchange format. It supplies a way of assembling Markdown knowledge, metadata, and links for consumption by people and AI agents.

The two could be complementary, with an OKF collection using Schema.org terms in its metadata.

Here’s an example:

---
type: https://schema.org/HowTo
name: Reset an API credential
description: How to replace a compromised API credential.
about:
- https://example.com/products/customer-api
dateModified: 2026-06-15
---

The risk is organisations that adopt OKF end up creating new local vocabularies for concepts that Schema.org (or iiRDS) already describe.

Documentation as infrastructure for AI

Many organisations currently see documentation primarily as something published for people to read.

In an agent-enabled organisation, documentation might also become operational infrastructure. For example:

• An AI support assistant might consult troubleshooting topics before responding to a customer
• A coding agent might use API documentation and architecture decisions while modifying software
• An operational agent might read a runbook, check a system, and recommend a recovery action

An opportunity for technical documentation teams

Technical communicators already specialise in turning fragmented, ambiguous and tacit knowledge into information that is:

• Explicit
• Organised
• Findable
• Consistent
• Appropriately detailed
• Maintained over time
• Suitable for a defined audience and purpose

These are also characteristics that make knowledge useful to AI.

A collection of poorly governed Markdown files will not automatically become a trustworthy knowledge base.

Someone still needs to decide what a concept means, which source is authoritative, how topics relate to one another, when information is obsolete, and who is allowed to approve a change. Those content governance questions.

What might change for technical writers?

If formats such as OKF gain traction, aspects of technical communication could become more prominent.

Writing for people and agents

Writers might need to consider how content will be interpreted by an AI system as well as by a human reader.

Richer metadata

Metadata might become a more visible part of everyday documentation work. A title and a few keywords might not be sufficient.

OKF version 0.1 deliberately specifies very little beyond a required type field. Organisations and vendors will need to decide which additional metadata conventions are useful.

More emphasis on relationships

Traditional documentation sites frequently organise information through navigation hierarchies. AI systems might benefit from more explicit semantic relationships.

For example:

• A procedure applies to a particular product version
• An error is caused by a particular condition
• An API supersedes another API
• A policy constrains a procedure
• A data field represents a defined business concept

Markdown links can express some of these connections, but link text and surrounding content will need to make the nature of each relationship clear.

Documentation that changes continuously

Google describes a model in which AI agents can help create and update the shared knowledge collection, while people curate and govern it.

This could lead to documentation workflows in which agents:

• Identify missing topics
• Draft descriptions from authoritative sources
• Update cross-references
• Flag conflicting statements
• Propose changes after a software release
• Identify content that appears to be obsolete

How the role might change

This does not mean the technical writer’s role would disappear. It is likely to shift further towards validation, architecture, governance, and editorial control.

Automatically generated knowledge can be confidently wrong, internally inconsistent, or based on an inappropriate source.

Human oversight is still needed, particularly where documentation affects safety, security, compliance, or financial decisions.

The unanswered questions

OKF is an early proposal; it’s not an established industry standard.

Unanswered questions remain:

• Will other major AI and documentation vendors support it?
• Will organisations converge on common concept types and metadata, or create incompatible local extensions?
• How will permissions and sensitive information be preserved when knowledge is exported?
• How will conflicting sources, variants, and product versions be handled?
• How will provenance and approval status be communicated reliably to an agent?

There is also a risk that organisations will mistake accessible content for good content. Converting an outdated wiki into Markdown does not make the knowledge accurate.

The quality of the source material still matters.

What should documentation teams do now?

There is no need to redesign a documentation platform around a specification that has only just appeared.

OKF could provide a useful nudge for organisations to review whether its documentation is ready to support AI-based services.

You could begin by asking:

• Can our documentation be exported in a clean, open format?
• Are individual topics understandable outside the surrounding website?
• Is important context stated explicitly?
• Can we identify the authoritative source for each piece of information?
• Do we record ownership, version applicability and review status?
• Are relationships between concepts represented clearly?
• Could an automated system distinguish current guidance from historical content?
• Are access restrictions preserved outside the authoring platform?

You could export a limited and non-sensitive documentation set as Markdown, add consistent metadata, connect related concepts, and test how effectively an AI assistant can navigate it.

This might also reveal weaknesses in the underlying content.

A new audience for structured knowledge

OKF might succeed, evolve into something different, or be overtaken by another approach. We don’t know yet.

It does represent part of a broader change. Organisational knowledge is no longer consumed only through websites, PDFs, help systems, and search results. Software agents also retrieve it, combine it, and act upon it.

That means documentation must be portable, attributable, structured and governable.

For technical communicators, this could be a significant opportunity. In an AI-enabled organisation, well-managed technical documentation might become part of the system’s intelligence.

Need guidance with AI?

Cherryleaf can help. See:

Is your content ready for AI? Find out before your chatbot does

AI documentation services

Using Generative AI in technical writing | ISTC accredited course

Managing and mastering documentation projects with AI

Note: This article incorporates some feedback from Lief Erickson and ChatGPT. The OKF examples were generated using ChatGPT.