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, 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
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 to compromise on having a Docs Liaison 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 Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 @desrosj @jeffpaul @johnbillion @peterwilsoncc @poena and @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, including the WordPress version pages and parts of the developer documentation.
For short, not everyone is willing to understand and follow thru with the full process and pages remain incomplete, like this or this.
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 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.
- Open a project in GitHub GitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ – Documentation Issue Tracker, example from 6.8
- 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.
- 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 article in the documentation handbook. The publishing of the pages has an order that is explained in the core handbook – releasing major versions.
For minor releases, only the HelpHub or Version release page is created and the 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 for both, user docs and developer docs.
Props to @milana_cap, @ninianepress and @4thhubbard for their feedback and review of this post.
