AI-Oriented Recipe Documentation

What problem existed?

The recipe catalog holds thousands of recipe pages, generated from the catalog, that serve several audiences at once.

Developers need to understand what a recipe does, whether it applies to them, how to run it, and what impact it will have. AI systems increasingly consume the same pages as context and grounding. The pages already held all of that information.

Because the pages are generated, their structure follows the shape of the catalog data. The opportunity was to design a structure aimed at reading and machine interpretation, working from the content that was already there.

Why did it matter?

Recipe pages sit at the intersection of product, documentation, and developer experience.

For many users, a recipe page is the first interaction with a capability before they ever enter the product itself. A stronger detail page could improve:

• developer understanding
• discoverability
• documentation quality
• AI consumption and retrieval
• product conversion

As AI-assisted development becomes more common, documentation gets consumed by both humans and machines. The structure of the content becomes as important as the content itself. That opened a window to rethink recipe pages as a shared interface layer between users, AI systems, and the product.

What constraints existed?

Several constraints shaped the work:

• Existing Docusaurus architecture needed to be preserved.
• Existing catalog generation pipelines couldn’t be rewritten.
• AI-generated summaries weren’t feasible at the time.
• The solution had to work using existing recipe metadata.
• The project was exploratory, framed to gather feedback rather than drive immediate implementation.

The goal was a realistic near-term direction rather than an idealized future-state concept.

What role did I play?

I drove the design exploration, from the information architecture through a working prototype, in partnership with the team that owns the docs.

My focus was the structure: an AI-oriented information architecture, a reusable page framework, and the patterns that make a recipe page legible to people and to machines. I built the prototype inside the actual documentation environment and validated it against real recipe data, so it could be reviewed under real content and real constraints rather than as a static mockup.

What options were explored?

A few directions came out of the exploration.

One approach focused on AI-generated summaries and insights at the top of each page. Another explored larger changes to the documentation platform itself. Both introduced significant implementation dependencies and uncertainty.

I went a different way and asked a more foundational question: what would a recipe page look like if it were intentionally designed for both humans and AI systems using only the data we already have?

That led to an exploration centered on hierarchy, semantic structure, metadata visibility, and content organization.

What tradeoffs were considered?

The main tradeoff was innovation versus implementability.

A more ambitious vision could have leaned on AI-generated content, new backend services, or extensive changes to the catalog generation system. The chosen direction sidestepped those dependencies. The design restructured what already existed. No new content. No new pipelines.

That kept the work grounded in today’s technical reality while still pointing toward a more AI-oriented future.

How did UX, engineering feasibility, and business strategy intersect?

The project deliberately operated inside existing platform constraints.

UX gains came from improved scannability, comprehension, and navigation. From an engineering perspective, the prototype demonstrated how the improvements could land using existing Docusaurus patterns, design-system components, and generated metadata. From a business perspective, the page becomes a stronger entry point into the platform by helping users understand the value of a recipe more quickly and creating a clearer path toward adoption.

How was AI used in the process?

AI played two roles.

It analyzed documentation patterns, developer tooling conventions, and emerging approaches to AI-oriented content structures. It also became a design-research tool for understanding the recipe ecosystem itself.

AI helped identify:

• Repeated information structures.
• Opportunities for semantic markup.
• Retrieval-friendly content organization.
• Reusable page patterns.
• Gaps between generated content and user needs.

AI worked as a researcher and analyst on this project. Content generation wasn’t part of the role. The wins came from compressing the distance between research, implementation understanding, competitive analysis, and design execution.

What was learned?

Documentation is no longer written only for people. It is increasingly consumed by AI systems, retrieval pipelines, assistants, and agents. That does not make documentation machine-first; good documentation architecture now has to support human comprehension and machine interpretation at the same time.

Strong structure around existing content is usually more effective than generating more of it.

What was the outcome?

A working prototype of a redesigned recipe detail experience built inside the existing documentation environment.

Key outcomes:

• A reusable page framework with native CSS sticky section headers and a measure tuned for reading.
• AI-oriented semantic structure using JSON-LD, semantic markup, and structured frontmatter from existing metadata.
• Structured metadata surfaced inline through a header card and a configurable Options card pattern.
• Accordion-based examples that let developers focus on one without losing the rest, paired with an inline diff view showing exactly what a recipe will change in real code.
• Length-adaptive sub-recipe rendering for the long tail of catalog complexity.
• Validated against four real archetypes spanning the catalog from simple to complex.
• Implementation guidance tied directly to the prototype.

The prototype showed how existing recipe content could become more legible to people, more legible to machines, and more likely to lead a developer into the platform.

The redesign ships with its own annotation layer. A Design Mode toggle reveals a wrench beside every section. Each one opens a small popover with the section’s status (New, Reframed, Real today, or Phase 2), the goals it serves (readability, AI parsing, conversion), and a one-paragraph rationale.

The second under-the-hood layer is invisible by default and surfaced on purpose. JSON-LD using schema.org’s SoftwareSourceCode type lives in the page head for AI consumers. A dedicated Structured Data section makes the same markup visible inside the page so designers, engineers, and reviewers can see exactly what the agents see. Every field maps to existing recipe metadata. No AI summaries. No authored copy.

More broadly, the work reframed documentation as a shared interface layer between developers, AI systems, and products, where the structure of the content matters as much as the content itself.

A leadership note: make it reviewable

This work had no mandate. It was framed to gather feedback rather than to drive immediate implementation. What moved it forward was building it as a working prototype inside the real docs environment, against real content, instead of presenting a deck. People could click through something real and react to it. When you are proposing a direction without the authority to require it, the most reliable way to earn the next step is to make the idea concrete enough that others can argue with it.