tl;dr – Local teams, such as [es.wordpress.org
] will be able to have their Handbook
for a complementary use of the global Handbooks, but adapted to the particularities of the local culture instead of relying solely on a translation of the English version.
Currently, we could group the Handbooks into three types:
All these documents are in English and are maintained globally by some members of the WordPress Community.
But, in some cases, especially the local teams of each country, region or locale, there are specific documentation needs that cannot be added to the global Handbook. The clearest example is a contextual documentation of translations (the differences between English and Spanish, or between Spanish from Spain and Spanish from Mexico), or onboarding documentation for a Local Community (for example, access to their Slack).
To this, we can also add documentation from other teams that affect local elements, such as events, being able to share presentations or WordCamp information from a territory.
Three years ago, a pilot project was started in the WordPress edition of Spain for the installation of the same Handbook plugin that is used in Make/WordPress teams.
This technology is available on several sites, but with very different results. One of the biggest problems is who has access to the site and who can propose improvements or make changes, with blocking or access limitations.
That is why the following proposal is raised, based on how is already working on the Make/Hosting.
The Hosting team has a Handbook that for more than 2 years has been managed entirely from GitHub. This allows its management within WordPress to be limited to the Team Reps of the team, who perform operational tasks (ordering and reviewing content.) Because the management user is WordPress.org, the attribution of the contents is not made to any contributor.
How is content attributed to contributors? Through GitHub, since anyone who collaborates in the repository will have a versioning of the changes, and their attribution in the Activity Tab of their Profile, thanks to the synchronization between WordPress Profile and GitHub. Contribution to WordPress Documentation can be gamified.
And, an advantage and disadvantage at the same time, is how it is documented on GitHub: with the Markdown markup language. This language is a de facto standard used in many projects and allows the creation of textual content in a simple way from the keyboard (and easily convertible to HTML). It is also the native text language of GitHub, which allows editing directly from the platform itself, without the need to install an external program. And although it is simple to learn, it has the disadvantage that you have to learn the basic syntax, and that you have to know how to use GitHub, although it has already been proposed that this is the tool for massive use of the WordPress Community.
From here, through a simple configuration, considering that the Block Editor can interpret Markdown natively and that there is a tool (already tested in the Hosting team) that synchronizes every 15 minutes any approved change in the Handbook repository with the WordPress site, being able to anyone in the world contribute to a team with a standard tool, whether you have a WordPress account.
As a starting point, the WordPress Community Spanish Team has been working for some time on a Handbook in which team folders and other useful folders for the Community have been created (such a general GitHub manual), and to which anyone can contribute.
This repository must be under the WordPress organization of GitHub, and apply the synchronization tool between that repository and the Handbook plugin, already installed on the [es.wordpress.org] site.
From there, anyone who wants it can contribute to the Handbook with new content, new ideas or suggestions through the automated system.
This should extend to the current Locale Managers of a management team of the edition of the locale sites, called Local Team Reps, and following the same philosophy of the Global Team Reps, being the Documentation Local Team Reps responsible for the approval and management of the publication.
Nowadays, the project for the WordPress Community in Spain is very advanced, and it would be immediate to be able to launch the pilot program of automation of local Handbooks, started 3 years ago.
Proposal by @javiercasares. Reviewed by @amieiro, @anagavilan, @estelaris, @glycymeris, @milana_cap, @mrfoxtalbot.
Pinging all Local Teams with Handbooks available, and Spain.