[00]
Documenting software that does not exist
We published docs before the plugins. Here is the rule that kept that honest, and how the changelog avoids the same trap.
- Written by
- The Subset team
- Reading time
- 3 min
- Tags
- engineering, docs
We built this site before the plugins were finished, so for a while the plugin pages described plugins we were still writing and the docs described settings screens that didn’t exist. Every plugin has published releases now, the docs describe the released versions and no page carries a placeholder banner. This post is about how we kept the earlier version of the site from misleading anyone.
Placeholders that look like placeholders
We had one rule: never show a placeholder that someone could mistake for the real thing. It started with screenshots. A mocked-up admin screen with plausible rows in it is a picture of software that hasn’t been written, and a visitor has no way to tell. So every screenshot frame on the site was visibly empty, with a caption saying what the real image would show.
Documentation was the harder case, because a confident sentence about a filter looks exactly like real documentation, and a developer will build against it. We wrapped every invented name in a marker component:
Open <Placeholder>Settings → Image Resizer</Placeholder> and set a maximum width.
Marked text renders differently on screen, and screen readers announce it as “placeholder, not final”. Each page also carried a status in its frontmatter, and a page marked status: placeholder showed a banner across the top:
---
title: Developer reference
audience: developer
order: 10
status: placeholder
---
Some pages never needed either. Which status code a redirect should use, or what the ePrivacy Directive requires, doesn’t depend on our code, so those pages went out as published from the first day.
Writing docs early had a use beyond having docs. A page forces decisions about which questions it answers, what a reader needs to know before changing a setting, and which extension points exist. Those decisions are cheap to change on a docs page and expensive once they’re in a released plugin. When rewriting a page meant changing how the plugin worked, we found out before anyone had installed it.
The changelog isn’t written by hand
The changelog went the other way. A hand-written changelog drifts as soon as someone ships a patch and forgets the page, or updates the page with the wrong version number. So /changelog/<plugin> isn’t a file. It reads the release table, the same rows the WordPress update check reads, and shows only published releases. A release that’s staged but not published is hidden there, as it is in wp-admin.
Releases are sorted by semantic version, not by date. A patch to an older line, such as 1.4.3 published after 2.0.0, would otherwise sit at the top of the page and look like the newest release. Sorted by version, it stays with the rest of the 1.4 line.
When we first published this post, the changelog said there were no releases yet. It now lists every published release, and nobody has edited it by hand.