Case Study

Designing AI-assisted developer portal authoring

tl;dr

Integrated an AI assistant into a developer portal editor to replace syntax-heavy workflows with guided, natural-language editing.

Designing an AI-native authoring experience for API documentation

Developer portals help organizations publish APIs for internal and external developers. Although the platform already supported sophisticated documentation experiences, authoring those experiences required developers to learn MDC—a syntax-heavy markup language that introduced unnecessary complexity into what should have been a straightforward editing workflow.

When AI became a strategic priority across the organization, I saw an opportunity to solve an existing usability problem rather than simply introducing another AI-powered feature.

Introducing “KAI” — the AI assistant — inside the editor. Rather than adding another chatbot, the assistant is integrated directly into the authoring experience so users can get contextual help without leaving the page.

Instead of teaching developers how to write MDC, I redesigned the authoring experience around natural language, allowing AI to translate user intent into correctly structured portal content while preserving the flexibility and control expected by technical users.

Solving authoring complexity over adding AI

The editor in its original state optimized for flexibility, not usability. Creating even simple layouts required understanding MDX syntax, component structure, and implementation details that had little to do with the user’s actual objective: Publishing polished developer documentation.

The challenge wasn’t helping developers write better markdown. It was eliminating the need to think about markdown altogether. Rather than approaching AI as a standalone capability, I positioned it as an interface layer that reduced the cognitive effort required to create, edit, and organize portal content.

Editing through MDC made even small changes fragile. Simple syntax mistakes were easy to overlook but difficult to diagnose, forcing authors to hunt through markup for missing characters or invalid values before they could continue editing.

Replacing syntax with intent

The central design hypothesis for this project was simple. Developers should describe what they want, not how to implement it. Instead of writing MDX directly, authors could express their intent conversationally while AI translated those requests into correctly structured content, layouts, and components.

This fundamentally changed the interaction model. Authoring shifted from constructing documentation through syntax to collaborating with an intelligent editing assistant that understood the user’s goals.

Discoverable, not intrusive. A contextual tooltip introduces the feature at the moment it’s most useful without interrupting experienced users’ workflows.

Natural language replaces syntax knowledge. Authors describe the outcome they want, such as applying a consistent theme rather than remembering MDC commands or component APIs.

Defining the boundaries of AI before designing the experience

One of the earliest design decisions involved clearly defining what AI should—and should not—be responsible for. Rather than replacing the editor entirely, AI became an assistant embedded directly within the existing authoring workflow.

Defining the product’s role. Early product principles kept Kai focused on reducing friction in portal authoring. Helping users make progress, generating structured content, and applying changes directly instead of acting like a generic AI chat assistant.

**Knowing when not to help;** Requests that affect the entire portal (such as global themes or navigation) are redirected to the appropriate tooling instead of producing misleading or incomplete results.

Its responsibilities included:

Creating and editing page content
Building layouts
Suggesting components
Correcting MDC syntax
Improving writing
Answering contextual questions about the current page

Portal-wide transformations remained intentionally outside the editor and were delegated to dedicated backend capabilities. Defining these boundaries early established clear expectations while preventing unnecessary overlap between AI features.

Designing for trust instead of automation

Introducing AI into a production editing workflow created a new design challenge. The question wasn’t whether AI could generate content. It was whether users could remain confident while AI modified their work. This principle informed every interaction throughout the experience.

Rather than immediately applying edits, AI previewed proposed changes before they affected the page. When requests lacked sufficient context, the assistant asked clarifying questions instead of making assumptions.

AI proposes, users decide. Rather than making silent edits, Kai generates a preview of changes that authors can review, accept, or discard before updating the page.

Every modification remained visible, reviewable, reversible, and under explicit user control. The objective wasn’t autonomous editing. It was collaborative authoring.

Designing around the moments where authoring breaks down

Rather than brainstorming AI features in isolation, I focused on understanding where authors consistently struggled throughout the existing editing workflow. Research, collaborative workshops, and concept exploration revealed recurring sources of friction:

Creating new pages
Learning MDX syntax
Correcting syntax errors
Building layouts
Reusing existing branding
Improving content quality
Understanding component behavior

These moments became the foundation for the interaction model. Instead of treating AI as a collection of disconnected capabilities, every feature was designed to reduce friction at an existing pain point within the authoring experience.

Preserving the editing experience while extending its capabilities

Users could continue editing manually whenever they chose while seamlessly transitioning into conversational authoring whenever AI could accelerate their work. This reduced the learning curve while allowing experienced users to maintain complete control over their content.

A core design principle throughout the project was progressive enhancement. AI wouldn’t replace familiar editing workflows, it would become another way of interacting with the editor.

Live collaboration with the editor. As Kai prepares updates, users can watch proposed changes appear directly alongside the rendered preview, reinforcing trust and keeping them in control.

Every AI-generated change is presented as a diff, making it easy to inspect modifications, copy individual edits, or revert unwanted suggestions.

Transforming an editor into an intelligent authoring environment

My involvement concluded before the feature reached production, so I can’t speak to its long-term adoption or business impact.

What I can confidently speak to is the design process that shaped it. Through research, concept exploration, and close collaboration with Product and Engineering, we transformed a strategic initiative into a coherent product direction grounded in real authoring challenges rather than AI novelty.

The work concluded with a fully defined interaction model, detailed design specifications, and a validated implementation strategy developed in close collaboration with Product and Engineering.

AI is always one click away. A lightweight floating action keeps Kai accessible from anywhere in the editor without competing with primary editing workflows.

Next Case