Akira Tachibana 2:10 pm on May 19, 2019  

Proposal: WordPress Developer Handbook for common topics

In DevHub (https://developer.wordpress.org/), we have Code Reference, Theme developer handbook, Plugin developer handbook, etc. but some topics are independent from those categories and quite common. For example,

What about creating the “WordPress Developer Handbook” for these common topics?

justinahinon 11:14 am on May 15, 2019  

Summary for Docs Team meeting 13 May 2019

Attendance

@kenshino, @milana_cap, @chrisvanpatten, @justinahinon, @atachibana, @naveenkharwar, @audrasjb, @ibdz, @mkaz, @aurooba, @asif2bd, @truongwp, @coffee2code

Content Migration from Codex to HelpHub & DevHub

@atachibana remembers that the first priority is redirecting Codex Pages to matches HelpHub Page. The guidelines for migration have been updated here: https://make.wordpress.org/docs/handbook/helphub/migrating-articles. The WP_Version pages are redirected at 50%.

The Docs Team is also still focusing on redirection on HelpHub before moving to the redirection on DevHub.

HelpHub development

@milana_cap is working on creating a guide for contributing with the code for HelpHub on Trac. The next thing to focus on will be to get it to a state where the installation script sets the project up easily.

Gutenberg Handbook

@coffee2code announced that the technical side of the migration of Gutenberg Handbook is almost ready and is now released on https://developer.wordpress.org/block-editor. There are still a couple of things to test including the redirects that currently syncs from a branch.

Use of the More Info section in Code reference

@juliobox previously introduced a question about the best way to use the More info section: https://make.wordpress.org/docs/2019/05/13/the-best-way-to-use-the-more-info-section.

The suggestion is interesting since that area could be useful as the user notes section, that can often be tricky and confusing. @atachibana and @kenshino thus suggested we should think about a better implementation for the More Info section. It could whether be a link to a handbook page that explains it further or some selected examples (self made or taken from user notes).

Any other comments or suggestions for this section are welcome and can be done into @juliobox post here: https://make.wordpress.org/docs/2019/05/13/the-best-way-to-use-the-more-info-section.

Centralised API Handbook

@kenshino suggested the entire API section (or most of it) inside a proper handbook that will cover both WordPress and WordPress.org APIs. Since there are not a lot of APIs, it will make sense to have all of them in one place.

Who’s in the Docs Team?

The Docs Team currently have a lot of contributors and many don’t stay long among other things because what is expected from them is not always very clear. This could be fixed by naming contributors a portion of the Docs Team duty to take charge of.

More informations about the Docs Team can be found here: https://make.wordpress.org/docs/handbook/about/the-team.

It could also be useful to assign contributors that want a team to lead, as:

  1. Docs Team Lead
  2. HelpHub Development Lead
  3. Content Lead
  4. User Notes Curator?
  5. Theme Handbook Lead?
  6. Plugin Handbook Lead?
  7. And more?

You can read a transcript of the meeting at :slack: https://wordpress.slack.com/archives/C02RP4WU5/p1557759622331500

Jon (Kenshino) 10:51 am on May 13, 2019  

Agenda for Docs Team meeting 13 May 2019

Our next Documentation Team meeting is scheduled on

Monday, May 13, 2019, 15:00 UTC

in the #docs channel on Slack

Current Projects Updates:

  1. Content Migration from Codex to HelpHub & DevHub – @atachibana
  2. HelpHub development – @milana_cap
  3. Inline Docs – @drewapicture and @atimmer
  4. Gutenberg Handbook – @dryanpress and @nosolosw
  5. Google Season of Docs – @chanthaboune

Ad Hoc pieces

  1. Use of the More Info section in Code reference – https://make.wordpress.org/docs/2019/05/09/more-informations-on-doc-need-your-feedback/
  2. Centralised API handbook – https://meta.trac.wordpress.org/ticket/4376
  3. Who’s in the Docs Team? (Let’s clarify this!)

Open Floor

Feel free to comment if you have items to add to the agenda.

Jon (Kenshino) 10:29 am on May 13, 2019
Tags:   

Summary for HelpHub meeting 6 May 2019

Attendance

@kenshino @milana_cap @atachibana @mkaz @kartiks16 @SallyinStC @felipeelia @tomf @kafleg @ibdz attended

Phase 1.5 – Development

@milana_cap outlined some VVV (local development tool) issues with Ubuntu 14.04 hitting end of life (EOL). It’s not absolutely a blocker to continue contribution work but it isn’t ideal.

@milana_cap also outlined 2 items that should receive a decision so that development work can start on it (small pieces)

  • https://github.com/WordPress/HelpHub/issues/237
  • https://github.com/WordPress/HelpHub/issues/231

A bug scrub was conducted on April 26 and the notes are available here – https://make.wordpress.org/docs/2019/04/28/helphub-bug-scrub-notes-26-april-2019/

Content Migration

@atachibana announces that migration of Phase 2 content is 100% complete.

@naomibush helped to transfer 19 Version (WordPress version notes) pages at WordCamp Atlanta, where she was leading the Doc team’s contributor day table.

@justinahinon added 4 new block editor pages based on classic editor docs.

As also discussed in the last Docs Team meeting, we’re shifting focus on the content front to doing redirections.

Gutenberg Developer Handbook

While not related to HelpHub, we also talked about the Gutenberg Dev handbooks that are being migrated to DevHub (developer.wordpress.org)

@mkaz outlined the following tasks that need to be done to release the handbook to the public

  1. Merge final PRs
  2. Publish to DevHub
  3. Confirm everything looks good
  4. Work with #meta to add redirects and disable previous auto-sync
  5. Confirm all looks good over week or two and rename to have just one manifest and retire old handbook

HelpHub Localisation

There have been technical suggestions from the meta team and I think we’re going to wrap up on what the Community and Docs team suggest as a first step.

We haven’t done that officially but I think we’re still going to recommend setting up the HelpHub plugin on Rosetta sites (other handbook CPT for community team) so that people can actually translate content right away.

If GlotPress becomes the tool we can use for long form translation, we can shift back to it when needed

You can read a transcript of the meeting at https://wordpress.slack.com/archives/C02RP4WU5/p1557154872221300

Julio Potier 10:15 am on May 13, 2019  

What’s the best way to use the More Info section?

Hello there, I’m Julio Potier. Long time contributor here and there, I loved to contribute to the french and english (old) codex.

Now it’s time to move on and use the new dev site.

However since it’s not a wiki anymore, we lose the possibility of total freedom. At the same time, we won an automatic parsing/filling !

Also, user notes (comments) are useful at the bottom of a page, it’s like php.net with the difference that a Doc team member has to verify and validate it.

BUT because there is a but, this is the point of this post. Sometimes there is a “More Informations” at the end of the page, before the users notes. Check that one for example, it’s my ideal case and I love it:

add_action()

For me, the interest is the same as php.net : provide a few examples of usage, some do&dont, some tips&tricks.

But not as a user notes, this is not “official” enough, anyone can add a user note, why would I trust one?

But this section is part of the page, the examples are (again) like php.net, THE examples.

So, I’m here to ask : do you/we want to keep that and let people of the doc team contribute to this “More Infos” box? Because I would like to help.

Voilà I would like to do this when I encounter a page that could need some examples. Of course, I’ll/can add user notes, it depends on the context.

So, I raise my hand to handle this, I appreciate your feedback on that 😉

Jon (Kenshino) 9:09 am on May 6, 2019  

Agenda for HelpHub meeting 6 May 2019

Hello all,

Next HelpHub meeting will happen on

Monday, May 6, 2019, 15:00 UTC
  1. Attendance
  2. Phase 1.5 Check-in
  3. Detailed content discussions
  4. HelpHub localisation
  5. Setup regular development bug scrub
  6. AOB

Helpful Links

  • HelpHub Staging – https://wp-helphub.com/
  • GitHub repo – https://github.com/WordPress/HelpHub
  • State of HelpHub (read for Phase 2) – https://make.wordpress.org/docs/2018/02/26/state-of-helphub-february-2018/
  • Previous Docs Team minutes – https://make.wordpress.org/docs/2019/04/30/summary-for-docs-team-meeting-29-april-2019/
Josepha 6:38 pm on April 30, 2019
Tags: ,   

X-post: 5.0 Release Retrospective Wrap Up

X-comment from +make.wordpress.org/updates: Comment on 5.0 Release Retrospective Wrap Up

2:28 am on April 30, 2019
Tags:   

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.

Jon (Kenshino) 2:41 pm on April 28, 2019  

Agenda for Docs Team Meeting 29 April 2019

Our next Documentation Team meeting is scheduled on

Monday, April 29, 2019, 15:00 UTC

in the #docs channel on Slack

Current Projects Updates:

  1. Content Migration from Codex to HelpHub & DevHub – @atachibana
  2. HelpHub development – @milana_cap
  3. Inline Docs – @drewapicture and @atimmer
  4. Gutenberg Handbook – @dryanpress and @nosolosw
  5. Google Season of Docs – @chanthaboune

Open Floor

Feel free to comment if you have items to add to the agenda.

Milana Cap 1:51 pm on April 28, 2019
Tags:   

HelpHub Bug Scrub Notes, 26 April 2019

HelpHub bug scrub is back. For the time being we’re planning to hold these once a month. If there’s a need, we’ll reconsider this decision. All the meetings will be happening in #meta-helphub channel.

At this point, HelpHub has two places for issues: Trac and Github. Our aim is to move all Phase 1.5 issues from Github to Trac as these issues are really just fixes for what is already live at wordpress.org/support. Phase 2 is planned to be worked on at Github for now.

Responsibility for Trac issues is very unclear and should be discussed between docs and meta teams. We don’t want to step on each other’s toes so it would be beneficial for both teams to make it clear who’s responsible for responses and decisions regarding reported issues.

At this bug scrub meeting we were discussing only Phase 1.5 issues.

Content

Content has only one issue on Github. @atachibana said he’ll comment on it and close it.

Another content related issue is opened on track https://meta.trac.wordpress.org/ticket/4195. It is highly recommended that content reps of documentation team get involved in discussion.

Design

We need decisions for 3 design related issues on Github. Also, we should see if @iviolini is still available for the project.

Development

Good first issues

During bug scrub we detected several issues that can be labeled as “good first issue”. They require either simple fix or just copying code from Github PR.

  1. https://meta.trac.wordpress.org/ticket/4267 – need switching h2 for h1 as explained here
  2. https://github.com/WordPress/HelpHub/issues/239 – has code in PR
  3. https://github.com/WordPress/HelpHub/issues/232 – has code in PR
  4. https://github.com/WordPress/HelpHub/issues/230 – has code in PR
  5. https://github.com/WordPress/HelpHub/issues/229 – has code in PR

Need discussion

1. https://github.com/WordPress/HelpHub/issues/237

We have to decide which is appropriate for HelpHub

  • To keep the order of TOC as like as (paper) book, or
  • To show the latest article as like as Search results

2. https://github.com/WordPress/HelpHub/issues/231

We need to properly redirect this URL https://wordpress.org/support/category/. It’s not directly accessible from anywhere but it is possible to arrive from, let’s say, here https://wordpress.org/support/category/advanced-topics/ by editing URL.

Ready for coding

Attendance

@atachibana @sergeybiryukov @felipeelia @milana_cap

You can read a transcript of the meeting at https://wordpress.slack.com/archives/CG47GT4G2/p1556290821016800

The next bug scrub will happen in late May. Date and time will be discussed and published prior.

#bug-scrub