[v4] Simplify Draft/Publish Workflow and Version States

[jessrynkar]

Goal: Simplify and add clarity to the drafts/publishing workflow, make states more explicit, and improve both UX and documentation.

Current Challenges:

• The distinction between draft: true, status: draft, and latest is confusing.
• Unpublishing or reverting creates versions that are indistinguishable from regular drafts/published docs.
• Querying with draft: false can unintentionally return draft content if no published version matches.
• Version history and main document interactions are not always intuitive.

Proposed Improvements:

1. Rename draft to latest: The current draft parameter is a major source of confusion because it updates the main document when true. Renaming it to latest will make it explicit that it controls which version becomes the main doc.
2. More Explicit Version Statuses: Introduce additional statuses to track whether a version was unpublished, reverted, or duplicated, rather than overloading draft. This preserves important context for each version.
3. Improved Admin UX: Update the versions table to clearly indicate the state of each version — e.g., draft, published, unpublished, reverted, duplicate — so users can understand at a glance what each version represents.
4. Better Documentation: Provide a clear, detailed breakdown of how versioning, main doc updates, publishing, unpublishing, and reverting interact, including recommended querying patterns to avoid exposing drafts unintentionally.

[PP-Tom]

I completely agree with this, it's the biggest part of friction I'm finding with clients and their editors. It's not entirely clear to them what status the page is actually in.

For example; we had a request asking why their page wasn't displaying. At first glance it was "Draft (has published version)", just like other documents that were "Draft (has published version)" that were showing. It was in fact it was unpublished by another editor. But it took a while to understand what was going off because the UI does not clearly communicate that status of the page.

I do sometimes wonder whether there is a deeper architectural issue around versions and drafts. For example, we couldn't unpublish a document because it was published before, but the draft currently wasn't valid. The document needed to be validated to unpublish.

This problem becomes deeper when localisation is involved, as each local is still technically one document, versions for that locale is also only one document. It makes it hard to track both versions and statuses around different locales.

Backend architecture is definitely not my forte, it just doesn't feel intuitive when working with these systems.

[PP-Tom]

One of these are unpublished, one of these is published but has changes. Telling which one is which is impossible from the list view.