For several meetings, one of the topics that has been repeatedly coming back and forth is the idea of updating some Test Handbook pages, which have been stalling a bit for a fairly long time, and it’s good to keep them freshly updated with the last decisions that have been coming from the latest meetings, especially regarding certain topics like the new testing protocols.

Future-Proofing Docs Changes

It is important that we address this as soon as possible to keep our processes up to date and efficient. More specifically, in the last meeting, @krupajnanda commented that maybe we should be updating based on the Test Handbook GitHub repo. All current active Test Team members found value in this change and agreed on making it possible.

Furthermore, we could also agree that working in the 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/ repo will let us have a perfect log of changes and reasons behind changes, plus having everything better documented than just making changes directly on the Test blog.

After taking a more in-depth look, it seems to be a great idea to start from that point, and from there, we will be taking the next steps to make this happen.

Working in GitHub also helps us share the responsibility of maintaining the team pages with other Test contributors, and not only the Test Team members locating issues and helping fix them.

Protocol to mirror the current docs with the tracker

First and foremost, we need to ensure that all existing documentation is accurately mirrored in the tracker to maintain consistency and track progress effectively. There was an attempt made 2 or 3 years ago, but the docs have changed partially, and not all the docs were fully mirrored back then. For the mirror sync to take place, all current docs in the blog must be removed first so they can be reloaded with the sync pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party.. We need to make sure with precision that the docs in the tracker are identical to the docs in the current handbook. We will have time to update them afterward, but first, the mirror should be as identical as possible. This task is not small and will take the following steps:

1. First, we need to check which docs remain the same.
2. Second, we have to add the missing docs with the best similar format possible.
3. Third, we must review all the assets (images, videos, etc.) and links.
4. Finally, we will have to make the table of contents manifest for the sync.

Collaboration and careful attention to detail will be essential throughout this process to ensure a smooth and accurate synchronization. A GitHub project will be created to track all the tasks in those four steps mentioned, assigned to each collaborator. Once we can confirm that the mirror is done, we can move into the next section.

Addressing Future Improvements to the Handbook

After the first step has been accomplished, we will need to execute the sync. For this process, @SirLouen will be contacting the MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. team, and in collaboration with them, we will enable the sync process.

Once we have the syncing up, we will be able to handle improvements easily with the GitHub Issue Tracker. Making decisions on what to change and what not to will be an important factor in how to handle this. But ideally, we should continue with the current format:

1. Commenting on and addressing these things in our meetings
2. Proposing a PR
3. After some validations by the Test Team, they will be added to the Handbook.

Test contributors will have the ability to create GitHub PRs on issues in their time and convenience and to offer suggestions using GitHub Issues, and these are what will then be discussed in the meeting on a certain day or in a certain meeting to ensure proper planning and transparency. These issues will then be sorted by the Test team to see which ones meet the criteria.

Test Team members will have write access to the repository, so they will be able to accept revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision., but still, all changes should undergo a meeting process before approval. Proposals should go into either a GitHub issue or a GitHub PR and be brought into the meeting. This approach will help maintain clarity, ensure quality control, and keep everyone aligned on updates.

Props to @mosescursor, @nikunj8866, and @krupajnanda helping review this article and offering feedback.

#docs, #test-docs