The Code Reference Runs Its Examples Now. Write DocBlocks Worth Running

Examples marked interactive execute in the browser against a real install, powered by Playground. It quietly raises the standard for your own documentation.

  • 2 mins read
  • 1 View
The Code Reference Runs Its Examples Now. Write DocBlocks Worth Running

The Code Reference has a Run button. Examples marked with an interactive PHP fence now execute in the browser against an actual WordPress install running on Playground. You read the example, press Run, watch it work.

Every developer has copied an example out of documentation, pasted it in, and found it did not work. Written against an older version, missing a required argument, or never run at all and quietly wrong since the day it was committed. An example that executes cannot stay wrong in that way for long, because the failure is in front of everybody reading the page instead of being rediscovered privately by each of them.

What this does to your own docs

If you maintain a plugin with a documented API, the standard just moved. An example nobody can run is now conspicuously less useful than one they can, and the habits that produce runnable examples are worth having either way.

Make examples self-contained: one that depends on three fixtures defined elsewhere on the page is a fragment, not an example. Include the setup, so if your function needs a post to exist, create one rather than assuming. Make the effect observable, because an example whose result is invisible teaches nothing. And keep them short enough to read in one pass. If yours needs forty lines, the problem is probably the API rather than the documentation.

Playground is turning into infrastructure

Step back for a second: this feature exists because Playground can boot a real WordPress in a browser tab, and that capability keeps turning up in new places. Documentation, plugin previews, bug reproduction, onboarding demos.

If you are not already using it for support, it is the best answer available to "it does not work on my site". A Playground link that reproduces the bug, with your plugin installed and the problem visible, saves a dozen messages about WordPress versions and active plugins.

Somewhere to start: take the three most-used functions in your plugin's public API and rewrite their examples so somebody could paste them into a clean install and watch them work. Small effort, unusually direct effect on your support volume.