Docs Focus role & workflow during WordPress release cycle

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 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 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-docs 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 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

Block Editor Handbook: restructuring project update (25 January)

This is the second update for the project to restructure the developer documentation of the 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. You can find the first update here.

The last two weeks we have been working on improving the documentation homepage. The PR for this has recently been merged, and the block editor now has a homepage with an improved structure. You can give a look at it here.

The next step for the next two weeks is to improve the table of contents of the documentation. The aim is to make it more consistent, and more complete.

The main exit to track changes to the table of contents is here. All contributions and ideas are welcome.

Thanks to all the people who contributed to the project; props to @mkaz @youknowriad @milana_cap @annezazu @paaljoachim.

#block-editor, #developer-documentation

Block Editor Handbook: restructuring project update (15 January)

This post is the first in a series that will be published regularly on the Make/CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. blogblog (versus network, site). The purpose of this series is to keep everyone up to date on the progress of the 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 Handbook restructuring project.

Currently, we are working on improving the handbook’s homepage. The goal is to make this page a real “Getting Started” page.

Someone coming to this page should be able to have a good overview of what the block editor is all about. They should also be able to find references to how to extend the block editor, how to contribute to it, or to the documentation of its main concepts.

The issue related to the handbook homepage improvement is here and here is the corresponding pull request.

Thanks to all the contributors who helped on the project this week 👏🏻.

#block-editor, #developer-documentation