Documenting software that does not exist

This site is deliberately ahead of the software. The plugin pages describe plugins that are being finished; the documentation describes settings screens nobody has built. That is a choice we think is defensible, and it is only defensible with a rule attached.

The rule#

Never render a placeholder that could be mistaken for the real thing.

It started as a rule about screenshots. A mocked-up admin screen with plausible rows in it is a picture of software we have not written, and a visitor cannot tell the difference — so the screenshot frames on this site are obviously frames, with the caption saying in words what the real image will show.

Documentation is worse than a screenshot in this respect. A confident sentence about a filter is indistinguishable from documentation, and somebody will build against it. So every invented name in the docs is wrapped in a marker:

Open <Placeholder>Settings → Image Resizer</Placeholder> and set a maximum width.

which renders as a marked run of text, with “placeholder — not final” available to a screen reader as well as to the eye. Each page carries a status in its frontmatter and wears it as a banner:

---
title: Developer reference
audience: developer
order: 10
status: placeholder
---

Some pages are just true#

Not everything in documentation is about the software. “Which HTTP status code should this redirect use” and “what the ePrivacy Directive actually requires” are questions with answers that do not depend on us having shipped anything, and those pages are marked published and carry no banner.

They are also, we suspect, the pages people will actually read.

The changelog takes the opposite approach#

A changelog is the one page where content is the wrong answer. Written by hand it drifts from the software immediately — somebody ships a patch and forgets the page, or edits the page and misremembers the version.

So /changelog/<plugin> is not a file. It is the release table rendered: the same rows the WordPress update check reads, filtered to published releases, ordered by semantic version. A release that is staged but not published is invisible here exactly as it is invisible to wp-admin, and the only way an entry appears is for a release to exist.

Today that page says there is nothing, which is correct and is the point. It is better to have a page that is honestly empty than a page that is confidently wrong.

What we would do differently#

One thing, already: writing docs before the software means the docs encode design decisions, and some of those decisions will turn out to be wrong when the code meets a real WordPress install. We will find out by having to rewrite a page and noticing that the rewrite is a design change.

That is a better failure than the alternative, which is finding out after release from somebody whose site broke.