Changing the nature of our weekly meetings

So HelpHub has already been deployed and other projects are in need of some focus.

I’ve been thinking about how to make our meetings more useful. Meetings that are just about updates aren’t the best use of everyone’s volunteer time.

Meetings that require involvement but no one is prepared for ain’t the best either.

So I’m hoping that we can improve how we run the meetings. I’d love for everyone to suggest something.

I’ll start off –

  1. Let’s rotate facilitators and note takers. Both roles have the ability to help someone really get into the groove and understand the Docs Team.
  2. Let’s change all meetings to Docs Team meeting (no special HelpHub dedicated only meetings)
  3. Let’s time-box each section of the meeting
  4. Let’s have focuses for each meeting. (e.g.)
    • Docs Team Meeting (60% time on HelpHub discussions, 40% other pieces)
    • Docs Team Meeting (60% time Docs Handbook, 40% other pieces)
    • Docs Team Meeting (60% DevHub discussions, 40% other pieces)
    • Docs Team Meeting (60% Flagship WordCamp contributor day discussions, 40% other pieces)
    • You get the drift!

Any better ideas? I’d love to hear them!

Summary for Docs Team Meeting 18 November 2019

Attendance

@kenshino, @atachibana, @kafleg, @milana_cap, @fierevere, @aurooba, @nullbyte, @audrasjb, @bph, @felipeelia, @felipeloureirosantos, @estelaris, @softservenet

Transcript

https://wordpress.slack.com/archives/C02RP4WU5/p1574089321150500

Topics

Notetaker & Facilitator selection

@aurooba volunteered to take notes and facilitate next week’s meeting.

HelpHub

This week’s meeting was a deep dive into 3 aspects of HelpHub, as identified by @atachibana.

Table of Contents

Home Page and side page navigation that should include TOC of whole HelpHub.

As I said many times, the failure of Codex caused by lacking of total TOC that produced so many similar pages and/or Orphan pages. We definitely need whole TOC in the Home Page and Side bar as like as other Handbooks.

– @atachibana

The overall consensus during the meeting was that the Table of Contents (ToC) should look like the sidebar of the Handbooks (for example, view the Themes handbook).

@estelaris was available for the meeting and shared the updated designs for the homepage and category pages.

@milana_cap suggested adding the number of articles in each category to the homepage, and @kenshino suggested adding a read more link to clarify there are more articles in the category than those that appear on the homepage.

On the category page, there is a sidebar, exactly like other handbooks, which can handle sub-categories and lists of many articles, including articles with long titles (they would wrap and have a slightly smaller font size adjustment).

Can someone tell me if the breadcrumbs are correct?

– @estelaris

It was clarified that HelpHub should not be in the breadcrumbs, and they should appear as follows: Home > Support > {name of category} / {article}

Except breadcrumbs would only make sense if an article doesn’t belong to more than 1 category. It can belong to 5 different categories

– @kenshino

@aurooba suggested that there be a primary category assigned for those articles that are part of multiple categories, to help clarify the breadcrumbs.

@estelaris clarified the breadcrumbs will be automated – for articles that are part of multiple categories, they will include the category name from where the reader followed the link.

There was a brief discussion whether breadcrumbs are useful and should be included, with folks chiming in that they are good for accessibility (@aurooba), helpful in mobile where menus are hidden (@estelaris), and good for giving you a sense of overall structure and your current position in it (@milana_cap).

@atachibana will summarise this discussion and post it as a reply to the updated P2 post @estelaris will create with the updated designs.

Article Timestamp

We need “last modified” time stamp for each article. Otherwise, I18N page can’t follow it.

– @atachibana

I would augment that display with a note of the wp version to article was first written.

– @bph

It was agreed that the article timestamp is needed for the I18N page and that it should be visible at the bottom of the page.

It being visible through rest api isn’t enough?

The main reason why I asked was because getting it through rest api (instead of waiting until it is displayed in the front end) would remove a possible stopper for i18n

– @felipeelia

@aurooba replied that it’s useful for regular readers to be able to see when an article was last updated.

Let’s consider 2 types of users:

1. Readers & content writers who aren’t tech savvy
2. Dev type people

– @kenshino

@atachibana will draw/write down his idea as a wireframe and post to P2.

Language Locator

Currently, the design from @estelaris shows the Language Locator as a dropdown.

@kenshino and @atachibana will follow up with locale teams to see what they would prefer as it primarily affects them.

Doc Team Badges

HelpHub contributors from other locales can get Docs Contributor Badge – no issues. Just get each local lead to submit names

– @kenshino

Open Floor

@bph pointed out that the Get Involved page needs updating to reflect the change in reps.

Suggested wording: “Documentation for Gutenberg is split into documentation for developers and end users (content creators). End user documentation is led by Birgit Pauli-Haack (@bph) and developer documentation is led by Paul Barthmeier (@pbrocks) in #docs channels. Connect with either Birgit or Paul if you’d like to help.”

– @bph

@milana_cap updated the page accordingly.

Agenda for Docs Team Meeting 17 November 2019

Our next Documentation Team meeting is scheduled on

Monday, November 17, 2019, 15:00 UTC

in the #docs channel on Slack.

Focus: Content

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Deep Content Discussions (40 mins)
    • HelpHub
      • Content Sync with localised versions
      • Discoverability
    • DevHub
  4. Project Updates (20 mins)
    • Common APIs Handbook
    • HelpHub (& localisations)
    • DevHub
    • Docs Team Handbook
  5. Open Floor

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

Summary for Docs Team Meeting 11 November 2019

Attendance

@atachibana, @kafleg, @yui, @Sanyog, @LeRoy, @tcarney, @leogermani, @bph, @ibdz, @felipeloureirosantos, @felipeelia, @estelaris

Topics

Wordcamp feedback

First topic was a feedback from WordCamps. We had WCUS, WordCap Tokyo and many others

In WCUS, @zzap introduced:

Please everyone welcome our new Gutenberg docs reps: @bph for end user docs and @pbrocks for developer’s docs.

@bph was in WCUS and informs that Jamie Wedholm also joined the team table and started a Google doc comparing current block doc with current core version of a block.

She is working Gutenberg end user documentation, organizing at https://trello.com/b/JnTCzOsL/gutenberg-end-user-docs

Helphub Localization

@estelaris asked about the language icon on the new HelpHub pages design

my question is regarding the use if the language options. I need to know how it works and if it is necessary to include it on HelpHub

It was pointed out that the discussions around it has been done in this issue on github: https://github.com/WordPress/HelpHub/issues/201.

@felipeelia highlighted

It is worthy noting that HelpHub translations are not linked yet (and probably won’t be in the near future). So, while it will be a very important element in the future, we wouldn’t have a way to implement it right now

The discussion went on how and where to present the language selector. There has been quite a consensus that it should be in the sidebar and the language must be written in the the languages’ format (not in english), with an autocomplete tool so users can find their own language.

We also discussed the possibility of auto-detecting the browser language and then suggest, with a more intrusive message right at the top of the page, that this page is also available in the browser’s language. (similar of what is done in other places in wp.org)

@esteralis will work on a first suggestion, while de dev team have to figure out when this can be implemented.

Docs Team badges

One more comment from @felipeelia:

During our first America’s Polyglots Meeting, @fierevere asked about Docs Team contribution badges being given to HelpHub collaborators
Also @yui had details.

@atachibana answers:

This is definitely important to involving many people into I18N HelpHub. Badge policy is not still fixed in Docs team, and this is another topic that @Kenshino (Jon) should decide.
He will lead the next week meeting and let him pick up this topic.

Common APIs Handbook

@leogermani says Internationalization Docs are live on the Common APIs Handbook: https://developer.wordpress.org/apis/handbook/internationalization/ and asks for feedback.

Once it’s ok, we can edit plugins and themes handbooks and remove the repeated content from there.

Transcript

You can take a look at the meeting transcript via this link: https://wordpress.slack.com/archives/C02RP4WU5/p1573484411030000

Agenda for Docs Team Meeting 11 November 2019

Our next Documentation Team meeting is scheduled on

Monday, November 11, 2019, 15:00 UTC

in the #docs channel on Slack. Today we will have feedback from Contributor Day in WCUS and WCTokyo. Unfortunately, @milana_cap who lead WCUS won’t attend the meeting. So any feedback from team members are welcome.

Also, we want to discuss about rename of Common APIs handbook so that it can cover common development topis such as I18N or license.

Items to discuss:

  1. Attendance
  2. Note taker
  3. Select facilitator for next Docs meeting -> Jon will run
  4. WCUS Docs Team Feedback
  5. WCTokyo Docs Team Feedback – @atachibana and @nao
  6. Content Migration from Codex to HelpHub & DevHub – @atachibana
  7. HelpHub localization
  8. Common APIs Handbook – @atachibana and @leogermani

Open Floor

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

Summary for Docs Team Meeting 28 October 2019

This meeting had an agenda to cover all the main topics:

Attendance

@felipeelia, @atachibana, @milana_cap, @tomf, @kenshino, @bph, @felipeloureirosantos

Topics

Updates

@leogermani updates:

Hooks migrations are stalled for the last two weeks

I’ve been working in the localization content for the common APIs handbook. Hopefully this week I’ll manage to have something to show

Docs handbook review: This page https://make.wordpress.org/docs/handbook/helphub/migrating-articles/ have 2 sections talking about migrating the Versions pages. Apparently this taks is completed already and could be removed

@atachibana updates:

Content: 256 of 1068 (23.9%) pages were redirected. Last week was 241 of 1068 (22.6%).

https://docs.google.com/spreadsheets/d/15hpEbbnuWJZ0DJafyCeG3CFRMtSxX1gY-RObrrjzzdw/edit#gid=1576070270

During these works, I was suggested by johnbillion to report all inline documentation fix under the one ticket: https://core.trac.wordpress.org/ticket/48303

I modified Docs Team Handbook to relect this change: https://make.wordpress.org/docs/handbook/code-reference/inline-documentation/

@estelaris updates:

The team at contributor day WC Valencia came up with good ideas, but after reviewing their individual input and adding the comments left on the P2 I posted 2 weeks ago, we came up with what it looks like the final version

Handbook

As discussed during our last meeting, our focus on this meeting was the Docs Team Handbook.

According to @milana_cap, our Handbook has been forgotten for a long time until recently when we started updating and reorganising it, each team member is responsible for a part on the Handbook, and may review and update all guidelines around it. It’s only natural that those people update the same parts of Handbook because they know the best how to contribute to that project and who to talk to.

@milana_cap also pointed out that we are also missing the Block editor documentation guidelines, and that we are missing someone who’s going to “own” it.

Then @felipeelia asks about the “Plugin Handbook Rep: Open” from the projects list.

@milana_cap remembers that plugin handbook is actually shared between plugin review team and docs, and that main ownership is by plugin team.

@Kenshino proposes about clarifies if the Plugin Team is updating the pages based on the latest changes to WordPress, and propose about contacting @ipstenu.

@milana_cap highlights that the main goal of the handbooks is that people that want to add something in notes or want to contribute, they should be able to go to our handbook, find info on how to start, which document to go to, which Trello board etc and which people to ping if they have questions.

@Kenshino gives the suggestion to create a P2 post, so we can set expectations and deadlines for people.

HelpHub

The plugin has been activated in several sites, but we are still waiting for content import into the sites. There is still not an estimation of its availability.

Next meeting & WCUS Contributor Day

We are going to be at WCUS 2019 Contributor Day, and @milana_cap has published a post about it: https://make.wordpress.org/docs/2019/10/28/docs-team-at-wcus-2019-contributor-day/

As we are going to be with limited resources next week, so the meeting has been canceled, and we will just have a meeting again on Nov 11 which will be hosted by @tomf.

Transcript

You can take a look at the meeting transcript via this link: https://wordpress.slack.com/archives/C02RP4WU5/p1572274864247300

X-post: Update: Contributor Orientation Tool

X-comment from +make.wordpress.org/community: Comment on Update: Contributor Orientation Tool

Docs Team at WCUS 2019 Contributor Day

Docs team will have a table at WCEU 2019 Contributor Day. We have few planned focuses.

Redirecting Functions in Codex to Code Reference (DevHub)

Details stats are here:
https://docs.google.com/spreadsheets/d/15hpEbbnuWJZ0DJafyCeG3CFRMtSxX1gY-RObrrjzzdw/edit#gid=157607027 Anyone can join these tasks by following below steps:
https://make.wordpress.org/docs/handbook/code-reference/editing-articles/

Docs Team Handbook

Review and report on missing/outdated parts. https://make.wordpress.org/docs/handbook/

Meeting Other Teams

Quick discussion with Plugins Team about Plugins Developer Handbook “ownership”. Same goes with Core team about Inline-Docs.

If anyone, who’s going to be present, have something else they would like to focus on, please leave comment here. Thank you and see you in St Louis.

Agenda for Docs Team Meeting 28 October 2019

Our next Documentation Team meeting is scheduled on

Monday, October 28, 2019, 15:00 UTC

in the #docs channel on Slack. As discussed during our last meeting, today we will focus on Docs Team Handbook.

Please review your parts of the Handbook. You can find out what’s your part by visiting team’s page https://make.wordpress.org/docs/handbook/the-team/ 

Items to discuss:

  1. Attendance
  2. Note taker
  3. Select facilitator for next Docs meeting
  4. Docs Team Handbook – @milana_cap
    1. What needs to be done
    2. Responsibilities
  5. WCUS Docs Team Table
  6. Content Migration from Codex to HelpHub & DevHub – @atachibana
  7. HelpHub localization
  8. Common APIs Handbook – @atachibana and @leogermani

Open Floor

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

Summary for Docs Team Meeting 21 October 2019

Attendance

@atachibana @softservenet @fahimmurshed @kafleg @verygoode @kenshino @fierevere @ibdz @audrasjb @leogermani @themiked @felipeelia @milana_cap @nullbyte

Format

Today we started with new meeting format. In order to make meetings more useful we want to try to keep updates as short as possible at the beginning of the meeting (or maybe even during day prior to the meeting).

Most of the meeting will be dedicated to one specific part of Docs team responsibility ― HelpHub is published and it will no longer have dedicated meetings every second week.

The rest of the meeting time will be used for quick discussions/decisions on any other part of Docs team work.

Also, whenever possible, it would be good to close the meeting with clear tasks for the next meeting.

Facilitators and note takers will be rotating. At every meeting one volunteer will be assigned for the next meeting.

Read more and leave feedback/suggestions on new format: https://make.wordpress.org/docs/2019/10/14/changing-the-nature-of-our-weekly-meetings/

HelpHub Updates

  • Content: 241 of 1068 (22.6%) pages were redirected. Last week was 230 of 1068 (21.5%).
  • Design: The team for WCValencia prepared some designs, but @estelaris needs to go through and to clean them up before presenting. Leave feedback for Home and Category pages here: https://make.wordpress.org/design/2019/10/14/new-design-for-helphub-home-and-category-pages/
  • Development: Development is blocked and waiting for designs and GIT/SVN shared repo.
  • Localisation (Rosetta release): More Rosetta sites got HelpHub activated. We are waiting for #meta team to import original HelpHub content. @audrasjb is going to open Trac ticket to hide automatic link to forums for locales that don’t use forums at .org.

Common APIs

@leogermani is proposing moving all documentation on internationalizing API and localising WordPress core, themes and plugins to newly published Common APIs Handbook. He will try to create all the necessary pages this week. After review the old pages from other Handbooks and Codex can be redirected.

Read more, leave feedback/suggestions and offer your help here: https://make.wordpress.org/docs/2019/10/17/l10n-and-i18n-on-common-apis-handbook/

Next Meeting

Next meeting will have focus on Docs Team Handbook. Everyone are invited to review their parts of Handbook and indicate things that are missing or are out of date. A plan on adding/fixing these should also be made.

What is my part of Handbook?

Every project has its part in Handbook. You know the best how to contribute to project(s) you are involved with and, therefore, you know better than the others if Handbook is complete and up to date for that specific project.

The team page is mapping responsibilities and will be used as general guide for Handbook parts ownership. If you are missing from the list or your responsibilities have changed since Team page was created, do let us know and we’ll fix it. Or you can fix it yourself.

Next meeting will be run by @felipeelia and will happen on

Monday, October 28, 2019, 15:00 UTC

Transcript of the meeting can be found here: https://wordpress.slack.com/archives/C02RP4WU5/p1571670035148100

Agenda for HelpHub Meeting 21 October 2019

The next HelpHub Meeting will happen in the #docs Slack channel at:

Monday, October 21, 2019, 15:00 UTC
  1. Attendance
  2. Select facilitator for next Docs meeting
  3. Content status @atachibana
  4. Design review – @estelaris
  5. Development (@milana_cap / @netweb)
  6. HelpHub Rosetta release
  7. AOB

Helpful Links: