Summary for Docs Team Meeting 29 April 2019

Attendance

@kenshino @milana_cap @atachibana @makewebbetter @chrisvanpatten @kartiks16 @mkaz @nosolosw @felipeelia @softservenet

Content Migration from Codex to HelpHub and DevHub

@atachibana reported that “Editing Articles” was modified to include the detail step of “Transfer”

Editing Articles

@kartiks16 offered to help with reviewing and publishing

@kenshino asked about the current focus of the Content Team

@atachibana reported almost all migrations were done and that they are in process of Transfer (Codex Page to HelpHub)

There is also a spreadsheet to track and modify status for HelpHub Gutenberg articles:
https://docs.google.com/spreadsheets/d/1PeHj7pSFLcdMbIC41JJdzEkl12TJT3mwWyzQv2mi01U/edit#gid=2125284625

@kenshino asked about a list of priorities related to content work:
1. HelpHub migration
2. HelpHub redirection
3. DevHub migration
4. DevHub redirection
5. DevHub’s example pipeline
6. Handbooks etc etc?

@atachibana reported that there is not a formal list of priorities, but that the order in the above list emulates the current situation in terms of priorities.

@kenshino suggested the priorities be outlined in the Handbook as priorities tend to change when an area needing focus is realized (and this could be adjusted as this occurs). It was also stated that this would help direct those helping on Contributor Days in terms of knowing what to focus on.

@atachibana will work on adding to Handbook, possibly in the below area, but to be included in this location:

Current Docs Projects

@kenshino pointed out that many Codex links are hub pages that don’t have a place in DevHub, for example:
https://codex.wordpress.org/Transients_API
-we need a way to deal with outliers like the API hub pages
-we need to put a high priority on redirection
-the idea is to move people from the Codex to DevHub and if that is not done rapidly, people will lose focus with the fact that the bulk are moving to DevHub
(same with HelpHub)

@kenshino suggested:
1. Setup a Core APIs handbook on DevHub to store all the hub pages. This will also allow people to add more pages to explain the use of transients etc
2. Start redirecting all top 100 DevHub pages
—>> examples can still be navigated to via the edit endpoint on the Codex
—>> the key right now is to get people interested in enhancing the DevHub pages
and helping with them

@milana_cap added that on every relevant DevHub page, a call should be placed for assistance with examples

@atachibana will create a Priorities page as discussed earlier and also create a Milestone

HelpHub Development

@milana_cap reported that the first Bug Scrub happened last Friday.

There were 5 first issues detected from existing PRs. 2 of these need discussion on the next HelpHub meeting and 3 issues are ready for actual coding.

@milana_cap additionally reported that there is a gap in Design and @iviolini may or may not still be available based on activity and that we should check on her availability.

@kenshino advised that he sent her an inquiry via direct message and that it might be difficult for her as a new starter to understand where design focus is and that he’ll advise when he hears from @iviolini

@milana_cap reiterated that there are 3 Phase 1.5 design issues needing designer opinion/action.

@milana_cap brought up another issue raised in the Bug Scrub that there may be some confusion now that issues are going to be moving to Trac that there be clear responsibilities between what the Meta Team does and what the Docs (HelpHub) Team does to avoid crossing over on issues.

@kenshino advised that there is already a HelpHub Category in Meta Trac and that it should work ok and raising an issue for HelpHub should be similar to DevHub and can either be fixed by the Team (HelpHub) or be held for other Contributors.

@milana_cap verified that we will now start creating issues in Trac with @kenshino, who verified that this is now the case. He also tagged @coffee2code so he would be aware.

@milana_cap also suggested that we’ll need a Handbook Page reflecting contributing to HelpHub relative to Trac.

Gutenberg Handbook(s)

@kenshino reported that @coffee2code has copied the Gutenberg Dev Handbook to:
https://developer.wordpress.org/block-editor/
—>> it’s available for us to comment and ultimately release when ready
@kenshino asked @nosolosw and @chrisvanpatten for feedback

@chrisvanpatten reiterated that a blocker for opening up the Handbook is the TOC issue and that the original plan was that the Gutenberg repo would house 3 handbooks: a Contributor Handbook, a User Handbook, and a Designer/Developer handbook. That’s why it was structured in the way it’s currently structured.

The User Handbook never made it into the repo, so now, only the Contributor and Designer/Developer Handbook are there.

@kenshino asked if a new Manifest could be created with the TOC changes @nosolosw suggested.

@mkaz suggested the initial idea was to use the manifest but only at the Designer/Developer node forward and then adjust as necessary.

@chrisvanpatten suggested going back to the editor channel and making a decision on where the Contributor Handbook lives.

@makz pointed out that although Gutenberg is part of WordPress, it’s also its own separately, which causes some issue in cases like these and that all of the Contributor items could just be the same WP Contributor Docs, but it’s run in GitHub and JS, so there are different processes.

@chrisvanpatten suggested the easiest path forward might be to create a second Manifest that only applies to the contents here:
https://github.com/WordPress/gutenberg/tree/master/docs/designers-developers
—>> then we can figure out if we want to rearrange the markdown files within the Gutenberg Repo as a separate step. @makz agreed on move over and then after-adjustment.

@nosolosw asked where the Gutenberg Contributor Handbook would live. @chrisvanpatten stated his opinion that there’s a strong case for the Contributor Handbook to live exclusively on GitHub and not be synced anywhere.

@nosolosw pointed out that other Handbooks have also have a Contributing Section.
https://make.wordpress.org/cli/handbook/

@mkaz showed there is a Contributing page here (on GitHub):
https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md

@chrisvanpatten suggested that the above could be made a sub-section of the Block Editor handbook. @nosolosw agreed that he was in favor of this approach. @mkaz stated his thought that the specific items to Gutenberg should be in Github, the general tone/voice/docs should be in WP.

@kenshino stated that the Contributor Handbook doesn’t have to be synced to DevHub.

@milana_cap pointed out an issue related to clicking on the edit button, which goes here:
https://raw.githubusercontent.com/*

@chrisvanpatten stated that it would either need to _move into_ the designer/dev handbook, or not move at all.

@nosolosw noted he didn’t see the benefit of splitting docs, that it would be better to have only one place for Block Editor Documentation.

@kenshino and @chrisvanpatten stated there wouldn’t be issues having it be a sub-section of the DevHub Handbook.

@chrisvanpatten stated the original concept/idea was that https://wordpress.org/gutenberg/handbook would continue to exist and reflect the latest version of the plugin and that the Contributor Guide would also live there, but that this seems to now be shifting to https://developer.wordpress.org/block-editor and that if this is the only place it will exist, that DevHub may be the right location.

@mkaz pointed out that there are different types of Users that will consume the information, Theme/Plugin Developers and those wanting to actually contribute to Gutenberg (although there would be less in that category). @nosolosw pointed out that these might often actually be the same people as the former would likely find bugs and issues and move forward with contributing to help deal with them. @nosolosw stated that often times, they’ll make the report, but not follow all the way through.

@kenshino stated that the next step should be doing a wildcard redirect of https://wordpress.org/gutenberg/handbook to https://developer.wordpress.org/block-editor/

@chrisvanpatten suggested the redirect be something like:
https://wordpress.org/gutenberg/handbook/designer-developers/* to https://developer.wordpress.org/block-editor/* and moving the Designer/Dev Docs to the top level before launch as it makes the TOC usable.

@chrisvanpatten also suggested to look at URLs:
https://developer.wordpress.org/block-editor/designers-developers/developers/block-api/block-registration/
is quite a lot vs https://developer.wordpress.org/block-editor/developers/block-api/block-registration/
—>> once it’s done, it would be launchable and we can move in the contributor docs later
—>> contributor docs should be addressed, but it doesn’t need to block the most critical docs getting in which will require a little more finagling on the GitHub/gutenberg side of things.

@kenshino stated the Meta Team is ready to implement changes and @nosolosw asked what the current proposal is.

@chrisvanpatten suggested this proposal:
1. Build a second manifest that only covers this folder: https://github.com/WordPress/gutenberg/tree/master/docs/designers-developers
2. Re-sync to DevHub
3. Implement a wildcard redirect: `wordpress.org/gutenberg/handbook/designer-developers/*` to `developer.wordpress.org/block-editor/*`
4. Launch
5. Figure out where to put Contributor docs
—>> once the initial work is done we can look at consolidating back down to one manifest, rearranging the folders in the GitHub repo, etc.
@kenshino suggested it could be called devhub-manifest
@nosolosw restated that he still disagrees with extracting Contributor Docs for launch.
@chrisvanpatten stated contributor docs would still live in their current location as a temporary stop-gap. They could be moved to DevHub later so as to not delay further.
@kenshino it can come in pretty fast as a sub section of the /block-editor/ setup
@ mkaz stated it’s good if docs ends up with same hierarchy Designer, Developer, Contributor but all at the same level
@kenshino suggested it could be /block-editor/developer /block-editor/design /block-editor/contributor, @chrisvanpatten agreed.
@nosolosw agreed and stated that the current manifest could/should be re-ordered to make those top level
@mkaz suggested to make the Manifest devhub-manifest.json and use that for import/sync and see how the results go
@nosolosw suggested to also move reference sections to top-level to fix the sidebar issue
@chrisvanpatten expressed concerns that if we reorder the current manifest, it will break the normal Gutenberg handbook, unless we disconnect it first
@kenshino stated reordering the current Manifest also reorders: https://wordpress.org/gutenberg/handbook setup when it next syncs which will cause the need for a lot of URL redirection.

As a summary, @kenshino asked @nosolosw once the new manifest is ready – to post in https://meta.trac.wordpress.org/ticket/4388 and @coffee2code can get it going. Further discussion and any more tech details can then be taken up in #meta-devhub everything progresses.

Other Issues/Items

Google Season of Docs: @kenshino asked @chanthaboune whether there was necessary support to participate and if we ended up applying. No response was received.

WCEU Contributor Day: @kenshino asked for who will be attending in addition to himself and @milana_cap and @milana_cap replied that there have been some that have applied for the Docs table.
@kenshino stated we’re gonna need people with GitHub merging capabilities around ideally, if it’s not possible, we could teach them to create PRs.

Character Encoding: @chrisvanpatten pointed out issues with many characters and that he’ll open a Trac Ticket if it seems to be an issue after the re-sync.

WP Coding Standards are now in DevHub: @kenshino provided the URL:
https://developer.wordpress.org/coding-standards/
—>> it’s also synced from GitHub so Developers can now make direct PRs to update things instead of worrying who has Core Handbook edit capabilities

WordPress API Handbook: @kenshino brought up that beyond the Core API handbook items discussed, we’re also looking to start up a WordPress.org API handbook:
https://meta.trac.wordpress.org/ticket/4376

DevHub Handbooks/References: @kenshino stated
DevHub is going to have 9 blocks of handbooks/references.

• Code Reference
• Coding Standards
• Themes
• Plugins
• Block Editor
• REST API
• WP-CLI
• Core APIs
• WordPress.org APIs
—>> 2 years ago there was only a Code Reference and Plugin Handbook,
so this marks quite a bit of progress.

————————————–

MEETING ACTION/AFTER ACTION

@milana_cap opened this ticket:
Meta Trac
#4419: Editor docs edit link points to raw github URLs
https://meta.trac.wordpress.org/ticket/4419

@chrisvanpatten opened a Draft PR that adds a manifest-devhub.json
https://github.com/WordPress/gutenberg/pull/15254
and pointed out that if it’s not too big a task, it’d be amazing if we could attempt to build the Block Editor handbook from this new manifest so we can get a feel for how it will look before merging.