Advanced Administration - New DevHub Handbook

[milana_cap]

During a discussion among Documentation team reps (there's no link, we did it in zoom), @kenshino, @atachibana, @estelaris and @milana_cap, we came up with a solution for unsorted documentation. This documentation currently lives in two places:

• HelpHub - parts we consider too technical for end user (almost everything under Technical guides column - ​https://docs.google.com/spreadsheets/d/11RxfocYIC8NjdS5em0yTk4eGGwZPhZbnR7E-CzUGT84/edit?usp=sharing)
• Codex - pages that are still not migrated to DevHub/HelpHub due to content not really fitting into developer or end user documentation

This handbook should cover topics that are too advanced for end users (for which they mostly turn to hosting support) but are not necessarily developer's tasks (even though historically developers performed these tasks) such as security, configuration, site maintenance, migration etc

We propose this new handbook to live in DevHub under name "Advanced Administration" and at following URL: ​https://developer.wordpress.org/advanced-administration/

This handbook will be maintained from the dahsboard so we don't need connected GitHub repository for it. All issues will be reported, discussed, and assigned in Docs Issue Tracker repo (​https://github.com/WordPress/Documentation-Issue-Tracker/).

[LucP]

I'll post it here for completion; I wouldn't mind being team rep for this handbook.

[milana_cap]

I attended ​Hosting team meeting where the Hosting team kindly offered their help in creating and managing content for this handbook. We agreed that we'd like this handbook to be generated from its own GitHub repository so the plan is as following:

• A new GitHub project, dedicated to collecting initial content for the handbook (from HelpHub and Codex), will be created and connected to Documentation team GitHub repo - ​https://github.com/orgs/WordPress/projects/47/views/1
• Issues for this project will be created in Docs issue tracker repo with ​advanced administration dedicated label.
• A new GitHub workflow for automatic adding labeled issues to the project will be created - ​https://github.com/WordPress/Documentation-Issue-Tracker/blob/main/.github/workflows/add-to-advanced-administration-project.yml
• A new GitHub bot notification will be created for advanced administration label, mentioning Docs and Hosting teams members who expressed interest in working on these issues - ​https://github.com/WordPress/Documentation-Issue-Tracker/blob/main/.github/workflows/notify-team-on-label.yml#L23
• A new GitHub repository, holding Advanced administration handbook content and manifest.json will be created and, at any point in time, transferred ownership to WordPress organisation - ​https://github.com/zzap/WordPress-Advanced-administration-handbook
• Hosting team members, interested in work on this, will be granted maintainers access to Docs issue tracker repo so they can work on these issues alongside Docs team members.
• Once the handbook is published, maintenance o it will be shared between Docs and Hosting teams, just as we have Themes handbook being shared between Themes and Docs teams.

[netweb]

We propose this new handbook to live in DevHub under name "Advanced Administration" and at following URL: ​https://developer.wordpress.org/advanced-administration/

This handbook will be maintained from the dahsboard so we don't need connected GitHub repository for it. All issues will be reported, discussed, and assigned in Docs Issue Tracker repo (​https://github.com/WordPress/Documentation-Issue-Tracker/).

One of the reasons to have a GitHub repository for the pages at ​https://developer.wordpress.org allows for easier contributions as contributors do not require a user account on ​https://developer.wordpress.org/wp-admin

Taking a quick look at the current repo, it looks like the above decision may have changed based on seeing the manifest changes being made here ​https://github.com/zzap/WordPress-Advanced-administration-handbook/blob/main/bin/handbook-manifest.json

If the above has changed, @milana_cap @javiercasares could we update the ticket to make note of that

Happy to help guide or create a patch for the above if this is required

[JavierCasares]

Hello

About this ticket, some answers / requests / changes (as the project evolves).

The main focus for this project "Advanced Admin Handbook" remains the same:

This handbook should cover topics that are too advanced for end users (for which they mostly turn to hosting support) but are not necessarily developer's tasks (even though historically developers performed these tasks) such as security, configuration, site maintenance, migration, etc.

Proposed this new handbook to live in DevHub under name "Advanced Administration" and at following URL: ​https://developer.wordpress.org/advanced-administration/

• ​GitHub Project
• ​Documentation Issues
• ​GitHub Handbook repo, need to be transferred to the WordPress organization.

Once the handbook is published, maintenance of it will be shared between Docs and Hosting teams, just as we have Themes handbook being shared between Themes and Docs teams.

There are coming some WordCamp / Contributor Day, and it will be useful if the Repo is in the WordPress organization, not only for control, but also for Activity record.

In the future (when the final "first version" has ended) we will use the "manifest" to sync it to the Site / Pages at developer.wordpress.org.

Regards, Javier.

[JavierCasares]

The first version for this Repo is done
​https://github.com/zzap/WordPress-Advanced-administration-handbook

Is it possible to move it into the WordPress org at GitHub so more people can contribute and have track of it?

[milana_cap]

Replying to JavierCasares:

The first version for this Repo is done
​https://github.com/zzap/WordPress-Advanced-administration-handbook

Is it possible to move it into the WordPress org at GitHub so more people can contribute and have track of it?

@dd32 I don't have access to create repo in WordPress org so can't transfer it from my account. How can we do this?

[dd32]

Replying to milana_cap:

dd32 I don't have access to create repo in WordPress org so can't transfer it from my account. How can we do this?

@milana_cap Either ping me on Slack when we're both around and I'll facilitate it with you, or you can transfer it to my GitHub account (@dd32) and I'll immediately transfer it to the Organisation when accepted. All GitHub redirects will work regardless of which direction you choose.

[milana_cap]

Replying to dd32:

@milana_cap Either ping me on Slack when we're both around and I'll facilitate it with you, or you can transfer it to my GitHub account (@dd32) and I'll immediately transfer it to the Organisation when accepted. All GitHub redirects will work regardless of which direction you choose.

I transferred it to you so you can do it when you get the time, it's simpler. Thank you so much 🙌

[dd32]

@milana_cap Repository has been transferred to ​https://github.com/WordPress/Advanced-administration-handbook

[milana_cap]

Replying to dd32:

@milana_cap Repository has been transferred to ​https://github.com/WordPress/Advanced-administration-handbook

Thank you so much.

Is this the right place to ask for access? If so, ​Documentation and ​Hosting teams should have maintain access and perhaps admin access for ​Javier and ​myself just to avoid bugging meta team for small things that might come up.

[dd32]

Replying to milana_cap:

Is this the right place to ask for access? If so, ​Documentation and ​Hosting teams should have maintain access and perhaps admin access for ​Javier and ​myself just to avoid bugging meta team for small things that might come up.

Done! I had assigned some of that upon transfer, but seem to have set y'all as read accidentally. Should be fixed now!

[milana_cap]

Replying to dd32:

Done! I had assigned some of that upon transfer, but seem to have set y'all as read accidentally. Should be fixed now!

It is, thank you a bunch ❤️

[milana_cap]

Hello @dd32, what can we do to make this handbook public? It is ready from the content perspective and has ​manifest.js file.

[dd32]

Replying to milana_cap:

what can we do to make this handbook public? It is ready from the content perspective

Thanks for the follow up, we were waiting on the content being ready before the handbook could be setup.

There's some work that needs to be done in WordPress.org code now to import it. I'm not 100% on the steps but hopefully it'll be setup when you get this response.

[dd32]

In 12504:

Markdown Importers: Jetpack's jetpack_require_lib() helper method no longer exists. Use direct file references.

See #6411.

[dd32]

Ended up needing to fix a bunch of broken things on the WordPress.org side, and fix the manifest file that was very incorrect.

See ​https://github.com/WordPress/Advanced-administration-handbook/pull/190 for the changes I made.

[milana_cap]

Replying to dd32:

Ended up needing to fix a bunch of broken things on the WordPress.org side, and fix the manifest file that was very incorrect.

See ​https://github.com/WordPress/Advanced-administration-handbook/pull/190 for the changes I made.

Thank you so much

[dd32]

@milana_cap Is there anything else needed here from the Meta side?

[milana_cap]

As far as I know, no. Thanks. The ticket can be closed now (I'd do it but I don't know what to resolve it with).