This is a summary of a discussion which happened during previous Docs Team meetings and also a proposal for WordPress 5.8.

During the previous weekly Docs team meetings, a discussion started about how the Documentation team could be better involved during WordPress release cycles.

In recent years, all new versions of WordPress have had a person responsible for the “Docs” focus (@justinahinon for 5.3 and 5.5, @audrasjb for 5.4 and 5.7, @sncoker, @m_butcher and their cohort for 5.6). But even if all the dev notesdev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. and the Field GuideField guide The field guide is a type of blogpost published on Make/Core during the release candidate phase of the WordPress release cycle. The field guide generally lists all the dev notes published during the beta cycle. This guide is linked in the about page of the corresponding version of WordPress, in the release post and in the HelpHub version page. (which are the main tasks of the Docs Focus) are published, the Docs team pointed out that it’s difficult for them to make sure all the end-user documentation (HelpHub) and the developer documentation (DevHub) are up to date after a new version is released.

WordPress release Docs Focus

@milana_cap (@zzap on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/.) is the Docs Focus Lead for WordPress 5.8. The role of Docs Focus lead includes the responsibilities listed below. For each responsibility, one or more deputies will help the release Docs Focus lead but Milana Cap will remain the unique Docs reference person for the Release squad.

Developers notes wrangling on Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.

• Keep track of changes within the release that require dev notes
  (changes that require a dev notedev note Each important change in WordPress Core is documented in a developers note, (usually called dev note). Good dev notes generally include a description of the change, the decision that led to this change, and a description of how developers are supposed to work with that change. Dev notes are published on Make/Core blog during the beta phase of WordPress release cycle. Publishing dev notes is particularly important when plugin/theme authors and WordPress developers need to be aware of those changes.In general, all dev notes are compiled into a Field Guide at the beginning of the release candidate phase. must be labelled with the needs-dev-note workflow keyword)
• Ensure all dev notes are written with enough time to proofread, reviewed, and published prior to the field guide (which is published by the Docs Focus lead at the same time as release candidaterelease candidate One of the final stages in the version release cycle, this version signals the potential to be a final release to the public. Also see alpha (beta). 1)
• Coordinate with the participants of those tickets with the best understanding of the changes (the committercommitter A developer with commit access. WordPress has five lead developers and four permanent core developers with commit access. Additionally, the project usually has a few guest or component committers - a developer receiving commit access, generally for a single release cycle (sometimes renewed) and/or for a specific component., component maintainers, the contributor who owns the ticketticket Created for both bug reports and feature development on the bug tracker.) to draft dev notes
• If a ticket participant is not available to write a dev note, finding someone to write one, or writing one yourself
• Proofread and review dev notes as they are available from the Documentation Wrangling team
  • Verify code examples
  • Make suggestions for additional examples
  • Ensure the developer notes accurately and thoroughly describe the problem, solution, and identify proper usage of the changes

End-user documentation wrangling on HelpHub

• Keep track of changes within the release that require changes on HelpHub
  (changes that require HelpHub changes (whether it’s a new page or just an update on existing ones) must be labelled with the needs-codex workflow keyword)
• Ensure any documentation pages required for new features are created before the release
• Ensure any existing documentation page for changes on existing features are ready to be updated (the day of the final release)
• Write and publish the release version page on HelpHub
• Update WordPress versions page on the Codex

Developer documentation wrangling on DevHub

• Keep track of changes within the release that require changes on DevHub
  (changes that require DevHub changes –whether it’s a new page or just an update on existing ones– must be labelled with the needs-docs workflow keyword)
• Ensure any documentation sections required for new features are ready to be updated (they are updated a few days after the final release, once the DevHub automatic parser has synchronized the documentation)
  • “More information” sections on DevHub (example)
  • BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor Developer Docs
• Ensure any existing documentation sections for changes on existing features are ready to be updated (they are also updated a few days after the final release)
  • “More information” sections on DevHub
  • Block editor Developer Docs

Workflow

A new spreadsheet will be created by the docs focus lead. The previous spreadsheet was built for dev notes over all, with a simple “HelpHub” column. For WordPress 5.8, the Docs team proposed to use a tab for each responsibility: Dev notes, HelpHub and DevHub, so they can be equally wrangled. Also, Core changes from TracTrac An open source project by Edgewall Software that serves as a bug tracker and project management tool for WordPress. will be separated from Block Editor changes from GitHubGitHub 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/.

Reviewed by @milana_cap and @jeffpaul.

#5-8, #developer-documentation, #devhub, #docs, #documentation, #helphub