Articles

Rewriting the MDN Dialog API Documentation

Name: Newism
Price range: $

The HTML <dialog> element is the modern way to build modals and popovers without re-implementing focus management, keyboard handling, and accessibility semantics from scratch. It’s a platform primitive, available across browsers since March 2022.

While researching the API, I found a broken live example on MDN. The show() method demo opened a dialog that couldn’t be closed. A small issue, easily fixed.

That simple fix turned into something much larger.

Finding the Problem

After submitting an initial patch, I decided to review the example patterns across all the HTMLDialogElement API reference and found a broader issue:

Examples were inconsistent across pages
Some demos included leftover form scaffolding unrelated to the API being documented
Key behaviours were mentioned but not clearly demonstrated
Event sequencing was described, but not observable

The documentation worked, but it wasn’t as clear or as precise as it could be.

The Scope of Work

What began as a small correction evolved into a rewrite of 12 documentation pages.

The goal was simple: each page should teach one thing clearly, and every live example should make the browser’s behaviour visible.

To get there, I:

Standardised HTML and JavaScript structure across all examples
Introduced consistent logging so event order is observable in real time
Removed distracting form logic from method-focused pages
Added explicit demonstrations of returnValue, which previously wasn’t clearly shown in action
Simplified markup so examples focused strictly on the API being documented

The rewrite wasn’t about adding more. It was about removing noise until the underlying behaviour was obvious.

Learning the MDN Way

Contributing to MDN isn’t just about being technically correct. It’s about teaching clearly at scale.

Through review with maintainers, I learned how MDN balances HTML element documentation with DOM API reference pages, when to use inline code versus cross-references, and how to structure live examples that explain behaviour without overwhelming the reader.

Even small conventions matter. MDN prefers ID selectors in JavaScript examples, reserving classes for CSS. Across a documentation surface this large, consistency is part of the user experience.

The review process spanned two months, involved multiple feedback rounds, and generated 70 comments before merging on January 26, 2026.

Why Documentation Matters

The <dialog> element looks simple, but it sits at the intersection of interaction design, accessibility, and browser behaviour.

It manages focus, keyboard semantics, and lifecycle state at the platform level. But it only works in your favour if you understand how its events actually behave.

The subtle parts are behavioural:

A close request can be intercepted, but a completed close cannot
cancel and close fire at different stages
beforetoggle reflects state transitions that are easy to misread
returnValue carries outcome data between sessions

When behaviour isn’t clearly demonstrated, developers waste time inferring how the API works.

Clear documentation removes that friction, so teams can implement with confidence and get on with the real work.

The Bigger Picture

MDN is one of the web platforms most valuable documentation resources. Improvements here compound across millions of developers building real products.

The real value wasn’t just contributing upstream. It was deepening understanding of the platform itself. You don’t truly understand an API until you can explain it clearly and defend every behavioural edge in review.