Move Handbooks to GitHub to ease ability to contribute content

[oglekler]

I didn't find Make Handbooks at GitHub, so, it looks there are no easy way to raise ticket and make PR with proposed changes. Tickets in Trac are much less convenient and transparent.

I propose to move all handbooks to GitHub and add at the bottom of each page a link to the source code, with a note that "if you want to propose change to this page, please, create a PR".

[JavierCasares]

There are some Make Handbooks synced with WP.

• ​https://github.com/WordPress/hosting-handbook
• ​https://github.com/WordPress/plugins-handbook
• ​https://github.com/WordPress/test-handbook
• ​https://github.com/WordPress/contributor-day-handbook

and some "developer" handbooks

• ​https://github.com/WordPress/Advanced-administration-handbook
• ​https://github.com/WordPress/developer-plugins-handbook

and a Rosetta site:

• ​https://github.com/WordPress/spain-handbook

[kaitohm]

In the Training Team, many of the contributors are not developers, and are therefor not familiar with the concept of creating PRs, or maintaining documentation in GitHub. For these reasons, updating the handbook in the Editor would seem to be “easier” for this team.

I think what’s needed is clear guidance in each team as to how the handbook is maintained, and where folks can raise issues when changes are needed. For example, Training has a handbook page that details exactly this: ​https://make.wordpress.org/training/handbook/faculty-program/editing-the-training-team-handbook/

[dd32]

Replying to bsanevans:

In the Training Team, many of the contributors are not developers, and are therefor not familiar with the concept of creating PRs, or maintaining documentation in GitHub. For these reasons, updating the handbook in the Editor would seem to be “easier” for this team.

I think this is the bigger problem, using GitHub for documentation is "easier" for a segment of the user-base, but it's not accessible to all, nor is it clear to many how it will look after converting markdown to WordPress Blocks (and Markdown is something that some absolutely love, and others absolutely hate). It works great for some documentation (ie. Block Editor, the docs and code changes can happen in the same Gutenberg PR) but can be total shambles for other content.

I don't personally see a problem with GitHub PRs as a way to manage suggestions, but I wish those suggestions didn't have to be managed via a GitHub account and PRs on markdown. Especially when WordPress is a CMS.

Using GitHub for handbooks is more of a workaround for the underlying issue of "WordPress.org doesn't have a way for users to offer textual edits and suggestions for content", without giving someone literal write access to an entire site.

The complication, is that while we could theoretically enable wiki-like functionality for WordPress.org handbooks and pages, teams and stakeholders would require/demand an approval flow and without a system in place to enable fast enough approvals of those suggestions, a wiki-system wouldn't exactly work.

To add to that though, this also brings with it some caveats for future translatability of the content, while it's easy enough to say "It's better for translators, they can fork it and create a new version!" that isn't ideal to keeping the translated form updated with new english changes, there needs to be a single source-of-truth that translations are based off. Gutenberg Phase 4 (Multilingual WordPress) will be reliant upon having WordPress posts as the source-of-truth, and managing the content outside of WordPress is going to create future work to support that.

tl;dr: Simply converting handbooks to GitHub "to make contributions easier" isn't easier for all, and causes other problems IMHO.

This is all to say; While GitHub offers some benefits to some, can we consider if it's actually the ideal solution before just accepting it as the solution?

Perhaps this is a situation where some teams could brainstorm or collaborate on new approaches?

[dd32]

As an example; the content for the main WordPress.org homepage (and sub-pages) are currently hard-coded ​in the theme for translation purposes, but with some horrible-to-manually-edit block HTML.

The block HTML is not edited directly however, instead it's edited via the Page Editor; and then sync'd to the theme source through a PR such as ​PR403 or ​PR401.

This isn't perfect, as the automated PRs (which are a new thing, it was previously a process of sending up a smoke signal, and a developer running the sync scripts) lack information about who made the edits and why, but let's them use the full power of the editor.

Would I suggest this exact process for handbooks? No. No I wouldn't. But it's a good example of a hybrid approach, where the page can be edited visually, but edits aren't made live without a review first.

[courane01]

Can we use ​https://github.com/wordpress/revisions-extended within WordPress to allow contributors to submit the revisions for review in the teams that don't want handbooks in GitHub?

[tobifjellner]

The handbook in make/polyglots is just a locally edited bunch of documents.

Some pages get manual updates now and then. For instance, we've got a list of CLPTE accounts. Whenever a new CLPTE is assigned, I add an entry to a list on a handbook page.

The idea of being forced to fork a repo, make that edit locally (probably directly in HTML), raise a PR, and finally commit it feels unneeded and heavy.

When some information needs to be updated, we discuss it in Slack and then I, or any other of our more than 60 editors can just update the document.

[flexseth]

Replying to courane01:

Can we use ​https://github.com/wordpress/revisions-extended within WordPress to allow contributors to submit the revisions for review in the teams that don't want handbooks in GitHub?

This was discussed in the #meta channel meeting today. I think it can be a good way to update simple revisions, IE:

​repeated words

​misspellings

These are simple fixes that can be done quickly, making closing out tickets a faster process.
This helps the ticket backlog not get out of control as new features are added.

Possible solution for simple docs updates

If it would be possible to look at the Revisions Extended plugin to make it a Canonical plugin, one supported by WP Contributors, this edibility could be improved going forward.

For example, an additional functionality to show revisions side-by-side, in a more visual manner. This would allow for more easily updating screenshots in the various documentation pieces and updating

Opinions on using the Block Editor for docs updates, in general

Going along the vein of "Doing things the WordPress way" - I think it's best to use the editor in WP to edit this content.

As @dd32 mentioned:

Especially when WordPress is a CMS.

Opinions on using GitHub to update content

I believe this sets up an additional step, that creates more tickets and more information spread out in an ecosystem (docs) that seems to be already a bit mirky. And the number of folks who will be able to contribute to documentation via PRs would could be not that much of a benefit, which really takes away the core power of GitHub.

Managing Pull Requests to automagically pull in new code. In the Handbook and docs in general's case, PRs won't achieve anything automatically so adding in another source of truth seems to make it more confusing.

Notes on timeliness of docs updates

via @tobifjellner

Then I, or any other of our more than 60 editors can just update the document.

In my experience I've found that there are a lot of updates that take a long time to get updated, even though there are 60 editors. Some of these editors may be inactive or only sponsored for 5% of their time, which isn't quite enough time when the software project is moving so quickly.

So I do agree on @oglekler's point that updating the info is a general need :)

[flexseth]

Replying to JavierCasares:

Thank you for linking these resources. I've been looking for the Plugins handbook for a good bit!

and some "developer" handbooks

• ​https://github.com/WordPress/Advanced-administration-handbook
• ​https://github.com/WordPress/developer-plugins-handbook

[JavierCasares]

A detail to consider is the documentation localization project.

In summary, the idea is to have the texts on GitHub, pass them through GlotPress, and have them end up on WordPress sites already translated.

I know this will depend a lot on what happens by the end of Phase 4, but for this reason, it was also decided to store handbooks and documentation on GitHub.

Another important thing is that not everyone has to auto-sync... one of those that is present but not synchronized is the Spanish one (for technical reasons that could be solved without needing to change the collations of the database).

There has been discussion and commentary on this process for over a year, and at the Community Summit 23, the conclusion was reached that this system, for now, is the least bad option, and that if in the future, when we have Phase 3 and Phase 4, it is decided to go 100% to WordPress, what we do on GitHub would not be lost and would serve the future of the project.

[JavierCasares]

Also, about "GitHub is difficult"... weve been working with very-non-technical people in Spain and with the documentation and a ​quick guide and a ​quick reference guide (that includes tips for the markdown migrator).

[dd32]

Replying to flexseth:

If it would be possible to look at the Revisions Extended plugin to make it a Canonical plugin, one supported by WP Contributors, this edibility could be improved going forward.

I'm not sure that's actually a viable option right now, it doesn't really achieve anything that's needed. There are other plugins that exist with the intention of having future-drafts with a edit/approval flow; but the biggest flaw in it all is the lack of a public edit log, a public editing interface, and publicly trackable awaiting-review text change suggestions.

Replying to JavierCasares:

In summary, the idea is to have the texts on GitHub, pass them through GlotPress, and have them end up on WordPress sites already translated.

There's zero need for Github to be involved in that process; It can just as easily (and perhaps even easier) pull from a WordPress post.

I don't know the background on the Community summit decisions, but it doesn't mean they were the correct decisions, or were made without input from those who were needed.

[JavierCasares]

The actual proposal / idea is based on this document:
​https://make.wordpress.org/project/2023/09/06/documentation-translation-localization/

Over time has changed to “go for GlotPress”, but in those meetings were @estelaris, @nullbyte, @milana_cap, @otto, @clorith, @kenshino, @coachbirgit, @femkreations…

Moreover, I know that @matt asked @estelaris for some requests, like the ability to discuss before and after the translation, be collaborative, etc. and that's why we went to in that way.

The last conversation was something like “this is the less bad option with the tools we have now”, so, if we have new tools, or we can add hundreds of people in the developer / documentation / handbooks, and their Rosetta sites, with almost unlimited revisions, ping when somebody makes some change, a review before publishing the update, and the possibility to notify everybody in other locales, is good for me. ;)

Actually, it's interesting because in the end, right now, all documentation is managed from GitHub, either by leaving the texts directly on GitHub, on Google Docs or similar… which end up becoming Markdown or WordPress content if people don't know.

As you all may know, Spain is one of the pilot projects of having the Handbook (in Rosetta) and we have been working so that anyone can publish, and in the past 3 months it is being done. Even, people who don't know how to use GitHub or Markdown have created manuals, available for everyone.

In any case, I'm glad this issue has been reopened. I ping @akirk and @amieiro as well.

[flexseth]

What about using the WordPress Playground to edit handbooks?

The Developer Documentation (Devhub) is set up in this way, but requires a good bit of wrangling to get up and running so you can offer up PRs. It could be possible to package up all of the content as a blueprint that could be imported to Playground to build the docs for editing purposes.

Possible user flow

• User sees something to fix or improve on a documentation page
• Page Bottom: Link to "Improve this page" - meets requested criteria
• Link directs user to pertinent user flow for building documentation for this page
• User downloads blueprint for this page's documentation, instantiates Playground
• User edits docs in the block editor
• User submits the edits (new blueprint) for review (this contains the changes)
• Handbook maintainers install blueprint to view changes
• If approved, handbook maintainers can copy/paste code from block editor to update

How would this work?

It would require porting the existing documentation to individual post imports via a WXR file.

Which could be done by running a wp-cli command to export each handbook page.

The handbook blueprints could be linked to an "Improve this page" contributor flow on each piece of content. The blueprint link to builds a Playground instance with the content to edit or improve.

Simple use cases

• Update screenshots
• Fix spelling or grammar errors
• add paragraph spacing

Optional improvement

Include a "Ready to Submit?" button for automated workflow to GitHub

Benefits

• Decouples individual content from understanding the entire handbook
• Contributor flows route content updates to relevant team
• Enforces use of the block editor, allows GitHub for collaboration
• Lowers barrier of entry to contributing to documentation teams
• No build requirements

[zieladam]

I prototyped a WordPress Playground documentation workflow based on @flexseth's idea.

It enables storing WordPress pages and uploads in a GitHub repo, editing and previewing them with Playground, and saving changes directly back to that repo. The’s a “Edit the Documentation” button and the video in the README demonstrates it:

​https://github.com/adamziel/playground-docs-workflow

I’d love to explore this in Playground and, if it pans out, discuss using it for other WordPress projects and handbooks.

[greenshady]

I can open a separate ticket if needed, but it would be highly beneficial to the folks who maintain the Theme Handbook to have this particular handbook connected to GitHub for management: ​https://developer.wordpress.org/themes/

Note that it is a part of the Developer Resources site, and therefore is a handbook in which developers contribute.

The current process is overly complicated and requires first filing a ticket here: ​https://github.com/WordPress/Documentation-Issue-Tracker/issues?q=is%3Aopen+is%3Aissue+label%3Athemes

Then, manually writing fixes in the ticket, which have to be transferred elsewhere. For new handbook pages, they are generally written in Google Docs to be reviewed. Then, they have to be migrated to WordPress.

With GitHub, it would give developers a tool that they are accustomed to using the ability to contribute to the Developer Docs. Right now, only 2-3 people actively contribute to the handbook at all. There's just such a huge barrier to entry that no one even bothers contributing (and, yes, I do get this direct feedback that folks would contribute more if it worked like the Block Editor Handbook).

With that in place, we could reintegrate WP via the Playground Docs Workflow project, as @zieladam mentioned.

[wildworks]

Regarding localizing the documentation, I would like to share the workflow that the Japanese community follows.

If the Handbook is managed on GitHub

• Fork the repository on GitHub.
• Clone the repository to our machine.
• Translate the text. Comment out the original text and add the translated Japanese text below it, as shown below. Example:

   <!--
   Hello World!
   -->
   今日は世界!
  

• Submit the translated page as a PR. Community members review and merge the PR (​example).
• Copy the markdown text of the translated page and paste it into the block editor on the Japanese Handbook site.
• If the upstream repository is updated, merge it into the Japanese repository. Here, we review the updates made in the upstream repository and make a new translation if necessary.

If the Handbook is not managed on GitHub

• In this case, too, create a repository for Japanese.
• Use the ​WP Block Converter tool to parse the published handbook page and convert it to markdown.
• Translate the text. Comment out the original text and add the translated Japanese text below it.
• Submit the translated page as a PR. Community members review and merge the PR.
• Copy the Markdown text of the page where the translation is completed and paste it into the block editor of the Japanese Handbook site.
• Periodically, run the WP Block Converter tool locally.
• If any differences are found, make a new translation.

In both cases, we use GitHub, and I certainly feel the problem of it being hard for users who are not familiar with GitHub to contribute.