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!

Agenda for Docs Team Meeting 9 December 2019

Our next Documentation Team meeting is scheduled on

Monday, December 9, 2019, 15:00 UTC

in the #docs channel on Slack.

Focus: HelpHub

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Deep HelpHub Discussions (40 mins)
  4. Project Updates (20 mins)
    • Common APIs Handbook
    • DevHub
    • Docs Team Handbook
  5. Select next focus
  6. Open Floor

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

Trac/Trello Discussion – The way to report and discuss documentation issues

This discussion started in Slack during one of Docs team meetings. It was discussion about the best tool for tracking progress and issues for block editor end user documentation. However, the question of tool is widely applicable to all Docs projects, hence the need for this post and discussion.

Having complete documentation on Codex made contributing to Docs team easy in a way that everyone, as long as logged in, could modify existing or add completely new parts of it. However, this method had its flaws. It was impossible to track which parts of documentation were modified. And if we can’t track modifications then we can’t check the correctness of newly added information as well as the quality of code examples.

It took few years but we moved big parts of Codex to new places, built on WordPress. While we have more control as complete content goes under our review, this move made contributions to documentation team fairly difficult. The process itself is unclear, different Docs team’s projects use different tools (none of which covers all we need) but the common scenario we end up with is people reporting issues in Slack #docs channel.

The Tools

Documentation team uses several tools in contributing process. We have several Trello boards with more or less activity. Also, progress for almost all projects is tracked in Google Docs.

HelpHub content is tracked in Google Drive while development uses GitHub repository for development and Meta Trac for production issues.

Contributing to code reference can be done with code examples through User Contributed Notes (e.g. User Contributed Notes for activate_plugin() function) or with inline documentation via Core Trac (which is more Core than Docs team’s responsibility).

Plugin developer handbook gets updated when someone reports issue in Slack channel while Theme developer handbook used to use Trello board but we handed over leadership to Theme Review Team (even though Docs team is still helping when needed).

Common APIs handbook uses Google Spreadsheet.

Block editor uses Trello board and Google docs for end user documentation and GitHub for developer’s documentation.

We also have Documentation Trac available. It hasn’t been used for anything before.

What is the problem?

Different projects have different workflows and, therefore, different tools. However, we have several problems to solve:

  • Access – while we do welcome everyone to contribute to Docs team, we also need to be careful with giving access to handbooks hosted at wp.org. If we want to make sure that only curated info gets into handbooks we need to limit access. That also means that whole burden of reviewing and maintaining handbooks falls on these few people who have access.
  • Keeping track of contributions and contributors – the easiest way to keep track of contributions/contributors is to use tools we have available at wp.org (Trac and Slack). On the other hand, Trac is not the most intuitive tool for wider range of WordPress users and Slack tends to burry information so the history is lost in tons of archives. Also, in some cases it is important that we have a history of a decision/discussion available at one, easy to access, place.
  • Project managing – each project is different but it is a project nevertheless. It is important that the tool we use for it have project managing features which will make contributing to the project easier (joyful is preferable).
  • Onboarding and taking over – Onboarding is huge problem of every open source project and it’s naive to think we can solve it with one tool. But also, it’s not just to tool we need to onboard people in, it’s the workflow as well. The tool we chose and the way we use it should be intuitive enough not to stand on our way to contribute and not to make project depended on a specific person. Most of this could be solved with a detailed documentation on the workflow itself.
  • There could be more, leave your thoughts in comments.

What are we deciding here?

We are not trying to decide on one tool over the other. We are trying to discuss all the tools we already use, how they solve our problems and how they help our workflow.

Most importantly, we want to figure out the way for reporting and discussing Docs issues. Preferably, we would come up with a unique way for all docs projects but given the differences between projects, it wouldn’t be considered as a failure if we don’t.

However, it is important that we come up with a way to report and discuss issues for each project. Results of this discussion will end up in our Handbook as a reference for contributing to Documentation team.

Please, leave your thoughts in comments.

Summary for Docs Team Meeting 2 December 2019

Transcript: https://wordpress.slack.com/archives/C02RP4WU5/p1575298831011000

Facilitator and Attendance

Facilitator: @kulsumsiddique

@kenshino will be facilitating next week’s meeting.

Attendees: @kenshino, @aurooba, @nullbyte, @atachibana, @ediamin, @bph, @softservenet, @leogermani, @ibdz, @fierevere, @chancestrickland, @Jaime-Wedholm, @carike

HelpHub Updates

@fierevere noted that content has been imported for all locales who requested it.

About 20% of the Japanese version was translated and redirected from the old Japanese Codex.

This Google Sheet tracks the status of the migration of other locales.

Gutenberg Docs work is organized in this Trello board, and @Jaime-Wedholm is working on notes for the Gutenberg Blocks documentation in this Google Doc.

DevHub Discussion

@leogermani has been working on the I18n Common APIs handbook page and will move on to deleting the common content from the Themes and Plugins handbooks and instead link to this new page.

@atachibana reported: Content: 264 of 1069 (24.7%) pages were redirected. Last week was 256 of 1068 (23.9%).

A previous conversation about the Common APIs handbook name (this discussion started as a P2 post from @atachibana) was revisited and concluded: For the moment, we’re not going to worry about the Common APIs handbook name. Later down the road, perhaps a better name will become suitable as more topics get added, the name can be revisited at that time. The Common APIs handbook will contain all APIs except the REST API, which has its own handbook.

@carike shared that the the Core Privacy team is planning a Consent API, which will be another topic to add to the Common APIs handbook.

Action Items

Agenda for Docs Team Meeting 2nd December 2019

Our next Documentation Team meeting is scheduled on

Monday, December 2, 2019, 15:00 UTC

in the #docs channel on Slack.

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Docs Team Handbook Discussion (40 mins)
    • Update on documents created at Google Drive
  4. Project Updates (20 mins)
    • 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 25th November 2019

Facilitator & Attendance

Facilitator: @aurooba

Attendance: @kenshino, @nao , @bph, @kartiks16 , @mkaz, @pbrocks, @milana_cap, @estelaris, @jaime-wedholm, @arnelcus , @nullbyte, @kulsumsiddique , @ibdz

Note-taker: @kartiks16

Next week Facilitator: @kulsumsiddique

Transcript

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

Docs Team Handbook Discussion & Tracking Doc changes across DevHub & HelpHub

  • To determine a few focuses and rotate amongst them. @kenshino wrote a P2 about this – https://make.wordpress.org/docs/2019/10/14/changing-the-nature-of-our-weekly-meetings/
  • @milana_cap came with a suggestion on noting down what were your problems, concerns faced by the one who facilitated the meeting for the first time.
  • @aurooba created a link https://docs.google.com/document/d/1hL49dGkpQOuUOJiBs-4p-EmGMVPjfHkLDQLI1LubnNE/edit to all additional questions/thoughts/concerns about facilitating in here so we can get this figured out.
  • @kenshino created a dedicated Google Drive Folder which contains different areas of Docs covers. We can start a document there for everyone to add their thoughts/questions about facilitating, and then work on creating a set of guidelines. It will be helpful for team members and for newcomers.
    Google drive folder: https://drive.google.com/open?id=1iDTW27QdF7dBtSHWAUiDIcrrD0hbgApO
  • Past discussion about assigning sections of the handbook to different team members: @milana_cap was supposed to write a p2 post about that. We can reuse trello board which we used for re-organizing the old Handbook.
  • Create a P2 Post on the discussion on how we would like to proceed ahead, Trello or Trac? @milana_cap will be creating a P2 post which will help to figure out on the trello/trac

Project Updates

  • @atachibana provided below update
    Content: 264 of 1069 (24.7%) pages were redirected. Last week was 256 of 1068 (23.9%).
  • HelpHub localization @milana_cap see some content has been imported to Serbian rosetta but some are still missing.
  • @nao started this status doc to collect team progress. Checking in with other teams now.
    https://docs.google.com/spreadsheets/d/1343cKHK5iV1TbOKuR57gcjkDV69xVik8QM_xjkJjDQI/edit#gid=0

Open Floor

  • @bph asked Block editor End-user Documentation is part of …… HelpHub? Answer to it is yes which is confirmed by @milana_cap

#meetings, #summary

Agenda for Docs Team Meeting 25 November 2019

Our next Documentation Team meeting is scheduled on

Monday, November 25, 2019, 15:00 UTC

in the #docs channel on Slack.

Focus: Docs Team Handbook

Items to discuss:

  1. Attendance
  2. Notetaker & Facilitator selection
  3. Docs Team Handbook Discussion (40 mins)
    • Adding a section on facilitating meetings
    • Areas of improvement + assignments
  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 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.