Summary for Docs Team Meeting 29 April 2019

Attendance

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

Content MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. 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 GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/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 APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways. 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 CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. 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 TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. that there be clear responsibilities between what the MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. Team does and what the Docs (HelpHub) Team does to avoid crossing over on issues.

@kenshino advised that there is already a HelpHub CategoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. 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 releaseRelease A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software. 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 GitHubGitHub GitHub is a website that offers online implementation of git repositories that can can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/ 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 BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. 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/PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party 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.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://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.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML. 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 sidebarSidebar A sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. 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 DayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-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 URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org:
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 APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/.
WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/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.