Docs Team Participation in WordPress Releases  ## Metadata - Author: [[Make WordPress Documentation]] - Full Title: Docs Team Participation in WordPress Releases - Category: #articles - Document Note: --- tags: - #wordpress - #documentation - #releases Author: Make WordPress Documentation Source: Make WordPress Reference: https://make.wordpress.org/docs/2025/09/10/docs-team-participation-in-wordpress-releases/#comment-40571 date created: 2025-09-11 00:00 --- # Title: Docs team participation in WordPress releases ## Table of Contents: - 🔗 [📝 Summary](#-summary) - 🔗 [📖 Main Content](#-main-content) - 🔗 [🗒️ Notes](#️-notes) - 🔗 [📖 References](#-references) - 🔗 [🗣️ Paraphrase](#-paraphrase) - 🔗 [📰 Newsletter](#-newsletter) - 🔗 [✅ Action Items](#-action-items) - 🔗 [🧪 Hypotheses](#-hypotheses) - 🔗 [📊 Methodology](#-methodology) - 🔗 [❓ Questions](#-questions) - 🔗 [🔮 Future Research](#-future-research) - 🔗 [💡 Implications](#-implications) - 🔗 [🧠 Learning Styles Assessment](#-learning-styles-assessment) - 🔗 [📊 Accessibility Assessment](#-accessibility-assessment) - 🔗 [🌍 DEIB (Diversity, Equity, Inclusion, and Belonging) Assessment](#-deib-diversity-equity-inclusion-and-belonging-assessment) - 🔗 [✅ Logical validity](#-logical-validity) - 🔗 [🔍 DARVO Analysis Prompt](#-darvo-analysis-prompt) - 🔗 [🔍 SEO Evaluation](#-seo-evaluation) - 🔗 [🎯 Conclusion](#-conclusion) ### References: - WordPress 6.9 Release Squad announcement (context referenced in the article) - Documentation Handbook: “Documentation process during a major version release” - Core Handbook: “Releasing major versions” - GitHub Documentation Issue Tracker (e.g., 6.8 project) Note: The article references these WordPress resources; link them in your internal knowledge base for quick access. ## 📝 Summary: The post argues that the current experiment to streamline the WordPress Release Squad by reducing roles has excluded a dedicated Documentation representative, which risks deprioritizing crucial documentation work. The author contends documentation is essential infrastructure—not a “nice-to-have”—and absence from the squad harms visibility, coordination, contributor motivation, and release quality. A temporary compromise appoints a Docs Liaison for 6.9, but the author calls for a permanent “Release Docs Lead” role in every cycle. The post outlines prior issues when non-docs members led documentation, gaps in the Core Handbook role definition, and summarizes the practical, time-sensitive documentation process across DevNotes and User Docs, both during and after the release cycle. ## 📖 Main Content: The core message is governance and process: streamlining the Release Squad has inadvertently removed formal docs representation, which undermines cross-team collaboration and creates coordination gaps. Documentation is framed as mission-critical to scale WordPress releases, ensuring feature comprehension, user adoption, and dev ecosystem stability. Historically, assigning the documentation lead to non-docs contributors produced mixed results due to role misunderstandings and lack of team context. The author urges reinstating a dedicated Release Docs Lead role, clarifying responsibilities in the handbook, and sustaining communication between Core and Docs. The operational workflow centers on a GitHub project tracking DevNotes (authored by core committers/feature owners) and User Docs (authored by docs team), with structured pre-release and release-day tasks, and continued post-release documentation updates. Personal insight: - This is fundamentally a socio-technical coordination challenge: reducing headcount helps overhead but risks under-specifying critical interfaces. Documentation acts as a coupling mechanism between product changes and user/developer understanding. Without a formal decision-rights holder (Release Docs Lead), work becomes best-effort, leading to incomplete artifacts (missing DevNotes, user docs lag). - The incentive argument is strong: absence from the squad and credits page impacts contributor motivation and recognition loops. Recognition is a governance tool; formalizing the role signals value and drives sustained engagement. ### 🗒️ Notes - Streamlined Release Squad experiment - Goal: reduce overhead on Release Squad through smaller team and stronger collaboration with Make Team Reps. - Risk: lacking a dedicated docs role results in overlooked documentation needs and weak coordination. - Why docs must be represented - “Documentation is not a ‘nice-to-have’… it is a survival requirement.” - Visibility and recognition: Without squad presence, new contributors see less pathway to top credits. - Alignment risk: Release planning can miss docs timelines and dependencies. - Interim arrangement for 6.9 - Temporary Docs Liaison agreed with @4thhubbard; must be re-evaluated each release. - Access policy: no new broad docs-site access to core committers who aren’t docs team; existing named committers retain access for now. - Role history and scope gaps - Past: anyone asking could be docs lead—even non-docs members—producing mixed outcomes. - Causes: role misunderstanding; lack of docs-team familiarity. - Handbook status: sections updated since 6.8; the “Documentation Wrangling” role is incomplete and potentially misnamed (over-emphasizes dev docs; omits user docs). - Actual documentation process (operational summary) - GitHub project per release (e.g., 6.8) tracks: - DevNotes: by core committers/feature authors; list by tech lead or release docs lead. - User Docs: by docs team; list by release docs lead. - Timing: both should be written during cycle; reality—often incomplete by release. - Release day (major versions) - Release-docs lead updates ordered pages per Docs Handbook (major version docs process) and Core Handbook (releasing major versions). - Minor releases - Create HelpHub/version page; update WordPress Versions page. - Post-release - Docs team continues updating/writing user docs; issues tracked in GH for user and dev docs. - Key pain points to address - Communication gaps between Release Squad and Docs team. - Perception that Releases are “core-only.” - Role clarity, authority, and incentives for Release Docs Lead. - Sustainable capacity to complete DevNotes and user docs within cycle. ## 📖 References: - WordPress Make: “Docs team participation in WordPress releases” (this article) - WordPress 6.9 Release Squad announcement (for the streamlining experiment) - Documentation Handbook: “Documentation process during a major version release” - Core Handbook: “Releasing major versions” - GitHub: Documentation Issue Tracker (example: 6.8) ## 🗣️ Paraphrase: 1) Original idea: “Documentation is not a ‘nice-to-have’… it is a survival requirement… Removing the role from the release squad… shows new contributors that working on docs will never get them to the top of the credits page…” - Paraphrase: Treat documentation as essential infrastructure. If you exclude a docs lead from the Release Squad, you signal—especially to newcomers—that docs contributions won’t be recognized at the highest level, which erodes both prioritization and motivation. 2) Original idea: “In past releases, the documentation team lead has been given to anyone that asks for… results have been a mix of good and bad… due to misunderstanding of the role and choosing contributors unfamiliar with documentation…” - Paraphrase: Historically, assigning the docs lead role to volunteers outside the docs team produced uneven outcomes. The main problems were confused expectations and appointing people without the necessary documentation experience. ## 📰 Newsletter: WordPress releases are getting leaner—and that’s a mixed bag for docs. The current experiment trims the Release Squad to cut overhead and boosts collaboration with Make Team reps. But there’s a catch: the dedicated docs role was cut, and that risks shipping features without the clear DevNotes and user guides we all rely on. Documentation isn’t optional; it’s the bridge between “it works on my machine” and “it works for millions.” For 6.9, there’s a temporary Docs Liaison—good start—but the community is calling for a permanent Release Docs Lead to ensure DevNotes and HelpHub updates land on time. Process still centers on a GitHub project tracking both DevNotes (by feature authors) and us - Summary: The release team is experimenting with a smaller team with the goal to reduce the overhead on the Release Squad. ” This streamlined structure places more emphasis on collaboration with the va… - URL: https://make.wordpress.org/docs/2025/09/10/docs-team-participation-in-wordpress-releases/#comment-40571 The release team is experimenting with a smaller team with the goal to reduce the overhead on the Release Squad. ” This streamlined structure places more emphasis on collaboration with the various [Make Team Reps](https://make.wordpress.org/updates/team-reps/), who are encouraged to help coordinate efforts from within their respective teams. The goal is to reduce the overhead on the Release Squad while still ensuring each team’s contributions and priorities are represented throughout the cycle.” as explained in the [Announcement the WordPress 6.9 Release Squad](https://make.wordpress.org/core/2025/08/19/announcing-the-wordpress-6-9-release-squad/) The release team does not include representation from the documentation team. Why is this a problem? Because often documentation gets overlooked in release planning and project-wide coordination: **Documentation is not a “nice-to-have,” it is a survival requirement.** It’s not something we *might* do if someone has time; it’s something we *must* do — or the whole thing breaks down at scale. Removing the role from the release squad, we are not just sending the message that documentation is not important, we are showing new contributors that working on docs will never get them to the top of the credits page, therefore showing that we don’t even appreciate contributing to the Docs. To support the smaller release team experiment, we agreed with [@4thhubbard](https://profiles.wordpress.org/4thhubbard/) to compromise on having a [Docs Liaison](https://wordpress.slack.com/archives/C02RQBWTW/p1756914956446299) for this release. But this needs to be rethought on every release. Docs needs a structure/inclusion in future releases which should be a lead. The feedback from the docs team so far on the experiment is the lack of communication from the release team and the perception that Releases are only open to core team members. For now, we will not give access to the docs site to core committers who are not members of the docs team. [@audrasjb](https://profiles.wordpress.org/audrasjb/) [@desrosj](https://profiles.wordpress.org/desrosj/) [@jeffpaul](https://profiles.wordpress.org/jeffpaul/) [@johnbillion](https://profiles.wordpress.org/johnbillion/) [@peterwilsoncc](https://profiles.wordpress.org/peterwilsoncc/) [@poena](https://profiles.wordpress.org/poena/) and [@sergeybiryukov](https://profiles.wordpress.org/sergeybiryukov/) currently have access and this will not be revoked. We can revisit this discussion after the experiment of a reduced release squad. #### Why is important to have a release docs lead The documentation team maintains the [user documentation](https://wordpress.org/documentation/), including the [WordPress version](https://wordpress.org/documentation/article/wordpress-versions/) pages and parts of the [developer documentation](https://developer.wordpress.org/). For short, not everyone is willing to understand and follow thru with the full process and pages remain incomplete, like [this](https://wordpress.org/documentation/wordpress-version/version-6-2-3/) or [this](https://github.com/orgs/WordPress/projects/235/views/1?pane=issue&itemId=101780534). #### Documentation team lead role in past releases In past releases, the documentation team lead has been given to anyone that asks for, even when they are not members of the documentation team. The results have been a mix of good and bad. There are two reasons, one is because of the misunderstanding of what the role is; and two, because the contributor chosen is not a member of the team thus they are unfamiliar with documentation. Since 6.8, we have worked on updating sections in the core handbook related to documentation. Yet, the Role of the Documentation team lead is incomplete. Beginning with the [Documentation Wrangling](http://Documentation%20team%20lead%20role%20in%20past%20releases) title, “wrangling” should not be on the title as it reads like the team only “wrangles” dev docs. It is also missing reference to the user documentation, whether is updating old articles or writing new ones for new released features. #### The actual documentation process This is a summary, the articles are linked for further explanation. 1. Open a project in GitHub – Documentation Issue Tracker, [example from 6.8](https://github.com/orgs/WordPress/projects/235) * In this project, DevNotes and User docs are tracked. * DevNotes are written by core committers or whoever has been involved in a feature. User docs are written by the docs team members. * Who creates the lists? DevNotes list is created by either the release tech lead or the release docs lead. User docs list is written by the release docs lead. * Both DevNotes and User docs should be written during the release cycle. Although, there is never enough time and both lists can be incomplete by the end of the release cycle. Docs team continues working on user docs. Any missing devnote is only updated if requested. 2. Before and on release day of a major version, other items need to be updated by the release docs lead. Full description on the [Documentation process during a major version release](https://make.wordpress.org/docs/handbook/workflows/documentation-process-during-a-major-version-release/) article in the documentation handbook. The publishing of the pages has an order that is explained in the [core handbook – releasing major versions.](https://make.wordpress.org/core/handbook/about/release-cycle/releasing-major-versions/) For **minor releases**, only the HelpHub or [Version release](https://wordpress.org/documentation/wordpress-version/version-6-8/) page is created and the [WordPress Versions](https://wordpress.org/documentation/article/wordpress-versions/) page gets updated. #### After the release cycle ends When the release cycle ends, the docs team focuses on updating or writing new user documentation articles. The work is tracked in the [GH documentation issue tracker](https://github.com/WordPress/Documentation-Issue-Tracker/issues) for both, user docs and developer docs. *Props to [@milana\_cap](https://profiles.wordpress.org/milana_cap/), [@ninianepress](https://profiles.wordpress.org/ninianepress/) and [@4thhubbard](https://profiles.wordpress.org/4thhubbard/) for their feedback and review of this post.*, Docs Team Participation in WordPress Releases, Make WordPress Documentation, 01k4wqkjnfvypvcmvat5dpc3gw.