New labels for WordPress Playground GitHub

[flexseth]

Based on existing docs and discussions, add new labels to organize this repo.

Helps project stakeholders and contributors to search and sort info

Think of this organizational strategy as if you were building out a WordPress website. How would you want the website user to easily have access to info pertaining to...

Also builds the framework for building the documentation out on a WordPress website 🫶

---

User Personas

• New User, End User
• Developer, Themer
• Training, Organizers
• Demo, Testing
• Contributor
• Advanced

Tags (labels)

• general info
• blueprints
• workflows
• plugin
• theme
• translations
• architecture
• file system
• database operations
• interfacing
• reporting, issues, bugs, feature requests
• command-line interface (wp-cli tips and tricks)
• migration (importing & exporting)
• troubleshooting

Documentation types

• tutorials (introduction to concepts)
• How to Guides (step-by-step instructions)
• Reference (APIs, Limitations, FAQ, issues & feature requests)
• Explanation) - sample blueprints and code

[adamziel]

Would the User Personas be labels? Or just the items listed as "Tags"?

Also, would they apply to all issues and PRs, or just the documentation-related ones? If it's the latter, I think I understand. If it's the former, what would be two examples of issues matching each of these? I'm trying to understand what falls under "plugin" or "interfacing".

[flexseth]

Would the User Personas be labels? Or just the items listed as "Tags"?

Answer: Labels

In the Documentation Issue Tracker we track issues by

• End User [HelpHub]
• Developer [DevHub]
• Themer [Theme Handbook]

This helps to structure doc updates by user persona.

---

Also, would they apply to all issues and PRs, or just the documentation-related ones? If it's the latter, I think I understand.

In the docs tracker everything is documentation related...

For this repo, I think the tags would best be used solely for Issues. Once a PR is created to address an issue, it can be attached as a comment to the Issue which provides a solid documentation flow for finding the info and changes.

Since you can drill-down based on is:issue or is:pull-request etc - the taxonomy would be filterable either way.

---

I'm trying to understand what falls under "plugin" or "interfacing".

plugins could be related to official Playground plugins, or using Playground to work on plugins
interfacing would relate to working with the Playground in non-native ways

[flexseth]

• Playground on W.org homepage #697
  [New User] label - someone who is new to WordPress

[adamziel]

Aha! Let me confirm my understanding:

• The WordPress/Documentation-Issue-Tracker uses persona and tags GitHub labels.
• The WordPress/wordpress-playground repo doesn't use them now.
• This issue is about creating those labels in the WordPress/wordpress-playground repo and using them for the documentation-related issues created in WordPress/wordpress-playground.
• The non-documentation issues in WordPress/wordpress-playground would not use those labels.

Is my understanding correct here @flexseth? If yes, let's do it. One caveat: I'd prefix those labels with [Doc] to clearly distinguish them from non-documentation ones.

Here's a few open questions:

• Would we also set up those labels in WordPress/playground-tools and WordPress/blueprints-library? If yes, I'll give you issue/labels access to those repos.
• Would it make sense to centralize those documentation related issues in the WordPress/Documentation-Issue-Tracker repo instead? Or do they still make sense in the respective project repos? Or would the project board act as the central location?
• Do you have the permissions necessary to create new labels in the WordPress/wordpress-playground repo or should I upgrade your access?

[flexseth]

Aha! Let me confirm my understanding:

• The WordPress/Documentation-Issue-Tracker uses persona and tags GitHub labels.
• The WordPress/wordpress-playground repo doesn't use them now.
• This issue is about creating those labels in the WordPress/wordpress-playground repo and using them for the documentation-related issues created in WordPress/wordpress-playground.
• The non-documentation issues in WordPress/wordpress-playground would not use those labels.

Is my understanding correct here @flexseth? If yes, let's do it. One caveat: I'd prefix those labels with [Doc] to clearly distinguish them from non-documentation ones.

The labels offer filtering ability. If a documentation author wants to work on something that is Docs and PHP-WASM related, they can filter for these terms to update the documentation. Or if a Playground collaborator fixes something with PHP-WASM and wants to let the Docs team know something needs to be updated, they can add the Docs label.

A GitHub workflow can be set up to email a notification when the Docs label is added.
That's how they do it in the Documentation Issues Tracker :)

Props to @zzap - Milana has done great work over there managing a TON of docs related issues.

Collaborator workflow

If collaborators want to work on open issues relating to PHP-WASM, they can search for the label.

Here's a few open questions:

• Would we also set up those labels in WordPress/playground-tools and WordPress/blueprints-library? If yes, I'll give you issue/labels access to those repos.

For best usability I think it would be a good idea to transfer the Issues to the appropriate repo.

Then we can look at taxonomy on a per-repo basis

---

• Would it make sense to centralize those documentation related issues in the WordPress/Documentation-Issue-Tracker repo instead?
  Or do they still make sense in the respective project repos? Or would the project board act as the central location?

The documentation issue tracker is great, but it's mostly for simple updates and end-users.

Playground is probably going to be a huge ecosystem so I think keeping all of the issues here, or in blueprints - or whatever makes the most sense is the best way to go.

• Do you have the permissions necessary to create new labels in the WordPress/wordpress-playground repo or should I upgrade your access?

Currently I can label but not create new labels. I can be very judicious when adding new labels.

Background

My background comes from one-part OCD and one-part ADHD.

Having things extremely organized is helpful for me, and I think it will be helpful for Playground collaborators and those looking to solve problems in the Playground ecosystem.

Concusion

If you can grant me the ability to add new labels to this repo, it would be a benefit.

cc @ironnysh and @SagarGurnani - Thank you for expressing interesting in helping with docs!

[adamziel]

Playground is probably going to be a huge ecosystem so I think keeping all of the issues here, or in blueprints - or whatever makes the most sense is the best way to go.

I'd like to keep this repo focused on Playground core. There was a time when we discussed everything here and it was just too much noise. WP-NOW is separate, VS Code extension is separate, Blueprints are spinning into a separate project that will work with and without Playground etc. Perhaps a separate repo for documentation work would be helpful, e.g. maybe we could work in https://github.com/WordPress/Documentation-Issue-Tracker/. What do you think @zzap? Or maybe a multiple repos with a central project board would suffice for now.

Currently I can label but not create new labels. I can be very judicious when adding new labels.

Hm I just went through GitHub permissions and don't think it's possible to grant access just to labels. Let's figure out the repository logistics and get those labels in place once we know where.

[flexseth]

Closing - unnecessary

Explaining the repos and having users search should be just fine for filtering info

• Playground repositories overview #1270

[zzap]

Perhaps a separate repo for documentation work would be helpful, e.g. maybe we could work in https://github.com/WordPress/Documentation-Issue-Tracker/. What do you think @zzap? Or maybe a multiple repos with a central project board would suffice for now.

@adamziel, if you plan on managing docs issues in the Docs Issue Tracker repo in the long run, then yes. If that would be a temp solution until you figure it out, then use the current solution as a temp. Not because we don't want Playground issues in Docs repo, but because of physics. The law of inertia says you'll have a hard time redirecting every report/issue to the new place. Doing it twice will be even harder. Twice as hard, apparently. Managing docs in a large open-source project with so many repos and places to consider and different teams/people to collaborate with, is already hard. Don't complicate processes if that doesn't improve something (contributing experience, quality of docs etc). The price is too high for the value you're getting.

[adamziel]

That makes a lot of sense, thank you @zzap !