Proposal to change the user documentation workflow

The workflow currently used by the Docs team to update user documentation is likely a key reason why documentation is often not ready by release day.

Current Workflow Overview

The GitHub project template contains 13 status columns, intended to reflect multiple review stages before publishing on WordPress.org. Some columns are used for Dev Notes, while others are for user documentation:

• No Status
• Unknown
• To Do
• In Progress
• F.G. and Misc.
• Needs 1st Review
• Needs 1st Review (Peers)
• Edits After 1st Review
• Needs 2nd Review
• Needs 2nd Review (Copy)
• Reviewed: To Revise / Migrate
• Ready to Publish: Make Core
• Done

Problems with the Current Workflow

Currently, once the Source of Truth article is available, contributors begin writing drafts—usually in Google Docs. These drafts often sit more than a week waiting for a first review. After revisions, they then wait again for a second review.

Sometimes the second reviewer publishes the article in WordPress; other times, articles wait weeks longer, and by the time they are updated, the release has already shipped, forcing additional updates.

This process leads to:

• A growing backlog of unfinished documentation,
• articles being updated out of release order (e.g., 6.4 → 6.6 → 6.5), resulting in confusion,
• inconsistent documentation when users report outdated content

Proposed Workflow Change

For WordPress 6.9, the HelpHub documentation was written directly in WordPress, scheduled for release day, without review waiting time.

To ensure accountability, issues were still created in GitHub to track both new and updated articles, and reviews should occur after publication.

Recommendations

• Skip most review stages before release.
• Form a small writing team dedicated to each release.
• Reviews should be optional before publishing (if a reviewer is available.)
• Schedule completed articles to publish on release day.
• Perform a second review after publishing, correcting any issues as needed.
• Simplify the GitHub project template to remove unnecessary review columns.

Key improvements shown by the new workflow