With each WordPress release, there are documentation updates that need to be handled to keep the documentation provided for users up to date and informative. This work involves a few steps: Identifying the updates, writing the updates, reviewing the updates, and publishing the updates.
This work is done by the Documentation team, is tracked in GitHub Documentation Tracker, and is discussed in the Slack #docs channel. As part of this work, it’s important to align with and check in with the release squad both to confirm what needs to be updated and to flag if any additional help is needed to manage the updates.
Getting access
To write updates to documentation, access is needed to the HelpHub site. You can either join in the Slack #docs channel explaining how you want to help with updates or upload your updates to the Release Project in 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 by the repository owner. https://github.com/. If you have not written docs before, you can also draft updates in a Google Doc and share the link in GitHub.
Identify the updates
Each release has a roadmap that’s shared at the start of the release cycle. This is an excellent resource to pull most likely items that will need to be updated, even as not everything in the roadmap will make it into the release at a high level. Issues can be added early in the GitHub Documentation Tracker then to track or at the point of BetaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process. 1 when the earliest stable version of the release is ready or RC1 when the release candidateRelease Candidate A beta version of software with the potential to be a final product, which is ready to release unless significant bugs emerge. is ready. At each of these points (Roadmap > Beta 1 > RC1), there’s an increasingly narrow and more likely list to act upon.
When you identify something that needs to be updated, first consider whether it needs a new document or if it’s an update to a current doc with the link to it. This will matter when you open a new issue. From there, add a new issue to the GitHub Documentation Tracker, pick the correct issue type, label it with a release specific label, and add it to the release specific project.
Write the updates
When writing new documentation, make sure you match the style and approach of the current. The easiest way to do this is to review the current documentation for similar features. For example, reviewing other 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. documentation if you’re writing a document for a new block in a release.
When updating a document, review the current screenshots to ensure they are up to date and keep in mind that an update might require restructuring the document itself depending on how far reaching the change is. Don’t just think about updating the documentation based on the current change but think about how the current change impacts the entirety of the documentation for users.
Always include a changelog or update the current changelog when making changes at the bottom of the documentation. This helps ensure everyone can see how a document has evolved over time.
Review the updates
After writing the documentation, reviews are needed. On the right hand side in GitHub, change the status under Projects to “Needs 1st Review”. Another member of the documentation team will then help review.
Of note, it can help to share in Slack in the #docs channel that work is ready to be reviewed.
Publish the updates
When the updates have been reviewed and are ready to go, schedule the updates to go live in line with the WordPress release, ideally within 30 minutes of the release itself. Sometimes releases can go live at slightly different times but it’s important documentation is updated as closely as possible with the release.
Tips and tricks
Each release has a release squad with a dedicated 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/ channel. Coordinate with that team as much as you need to in terms of progress on docs, what needs to be updated, and what support is needed.
Schedule the documentation updates to go live at the same time. This helps with keeping track and ensuring a cohesive update is done at once rather than being rolled out in a staggered way, which can make it seem like certain docs weren’t updated in time.
Use a test environment like WordPress Playground to explore the features being written about for the release, to take screenshots, and more. Don’t just rely on reading pull requests or issues as features can change drastically throughout the release process and it’s always best to use the release when writing about it.
