How to Keep Your Docs Version in Sync with Your Latest Release
You ship version 2.4 on Monday. On Friday, every doc still says 2.3, because the version badge was typed by hand and nobody remembered it. Readers then wonder whether the docs describe the plugin they actually have.
To keep your docs version in sync with your latest release, you tell the docs collection to take its version from the product’s changelog. Core Support then shows the changelog’s current version on every doc in the collection, and it changes the moment a new release reaches the changelog.
Core Support is my help desk plugin for WordPress, with docs and changelogs built in. If the changelog already syncs from GitHub, as How to Automate Your Changelogs from GitHub sets up, nobody types a version number anywhere again.
Before You Start
- A docs collection for the product, under Core Support → Collections.
- A published changelog for the same product, under Core Support → Changelogs, with at least one release.
Where the Version Shows
The collection’s version appears as a badge under the title of every doc in it, next to the “Updated” date. One setting on the collection controls all of them, and a single doc can still override it.
Current version on the collection has 3 kinds of choice:
| Choice | What the docs show | Good fit when |
|---|---|---|
| No version | No badge at all | Docs that apply to every version, or a service with no versions |
| Type a version | The version you typed, up to 40 characters | A product without a changelog in Core Support |
| From the {Product} changelog (now X) | The changelog’s current version, updated with each release | Any product with a changelog in Core Support |
Link the Collection to Its Changelog
- Open the changelog under Core Support → Changelogs.
- In Product details, set Docs collection to the product’s collection and save. The changelog gets a Docs link and the collection page gets a Changelog button.
- Go to Core Support → Collections and edit the collection.
- Open Current version. The linked changelog is listed first, as “From the My Plugin changelog (now 2.4.0)”.
- Choose it and save.
Step 2 is optional for the version itself, because the menu lists every published changelog. Linking them is still worth it: readers get a path between the docs and the release notes, and the right changelog sits at the top of the menu.
How the Current Version Is Picked
The current version is the changelog’s newest stable release. Versions ending in -beta, -rc or -alpha, and releases GitHub marks as pre-releases, don’t count. If a changelog has no stable release yet, the newest release of any kind is used.
So shipping 2.5.0-beta.1 doesn’t change your docs, and shipping 2.5.0 does. That’s the behavior you want: docs describe what most customers run, not what a few testers are trying.
If the linked changelog is unpublished or loses all its releases, the collection falls back to the version typed under Type a version, if there is one.
Override the Version on One Doc
Some docs describe older behavior on purpose, such as a migration guide for 1.x users. Those can carry their own version:
- Edit the doc.
- In the Doc details box, fill in Applies to version, such as
1.x. - Save.
Applies to version wins over the collection for that doc only. Leave it blank on every other doc so they keep following the changelog.
Pair It with Last Reviewed
A current version badge says which release is out, not whether a doc was checked against it. The Last reviewed field in Doc details does that job. Tick Reviewed today when you check a doc after a release, and its “Updated” line shows that date.
Core Support → Docs insights lists published docs not edited in 6 months, oldest first. After a big release, I’d work down that list and review the docs that touch what changed.
Check It Works
- Open any doc in the collection on the front end and note the version badge.
- Add a new stable release to the changelog, or let it sync.
- Reload the doc. The badge should show the new version.
If it doesn’t change, check that the release is stable and that the changelog shows it as Latest on its own page.
What It Won’t Do
- It doesn’t rewrite your docs. Only the badge changes. Setting names and screenshots in the content still need a review after a release.
- It doesn’t follow pre-releases. Use Type a version if a collection documents a beta on purpose.
- One collection takes one changelog. A collection covering 2 products with separate versions needs Applies to version on the docs that differ.
Readers who want to know what changed in that version can follow the Changelog button to the release notes. How to Publish Release Notes Customers Actually Read covers making those worth opening.