Summary for Docs Team Meeting 9 December 2019

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

Facilitator and Attendance

Facilitator: @kenshino
Note-taker: @ibdz

@kulsumsiddique will be facilitating next week’s meeting.

Attendees: @kenshino, @FahimMurshed, @atachibana, @ibdz, @kulsumsiddique, @mukesh27, @ediamin, @fierevere, @Carike, @nullbyte, @bph, @udfibonacci, @felipeelia, @estelaris, @leogermani

HelpHub Updates

@atachibana reported that there are no any movements for HelpHub except new release notes such as 5.3. The team is working on some page of Gutenberg User Guide that was missing.

@kenshino started an idea to do a survey to find out the completeness and quality of end-user documentation. The survey is targeted to go out by February 2020. @atachibana and @bph will help create a survey about all end-user documentation.

HelpHub Localisation

@atachibana updated that there were 30 Japanese Codex pages migrated to Japanese HelpHub on the Contributor Day at WordCamp Osaka.

Common API Handbook

@leogermani fixed some error on i18n page and has been working on editing plugins and themes handbooks.

DevHub Updates

@atachibana reported: Content: 280 of 1069 (26.2%) pages were redirected. Last week was 264 of 1069 (24.7%).

Next week meeting focus

@kenshino suggested about next meeting focus on discussing the Docs team organisation generally which could include Badges, Handbook, Management, or Meetings.

@kenshino asked all contributors who’d like to join Docs team regularly to give feedback to this post (https://make.wordpress.org/docs/2019/12/08/trac-trello-discussion-the-way-to-report-and-discuss-documentation-issues/) before next meeting.

Open Floor

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.

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:

Summary for HelpHub Meeting 9 September 2019

@kenshino @milana_cap @leogermani @kafleg @aion @softservenet @Pieter @audrasjb @estelaris @bph @joyously

Development

Development of HelpHub was blocked for 2 things and discussed:

@estelaris commented for HelpHub design:
https://docs.google.com/spreadsheets/d/1ZnhtiLxqjXviFlnWsDE5L8YRiBXtkmanvM8doIc1lrg/edit#gid=0
This is the document to gather all the requirements docs team has.

Design team review

They reviewed two things:

  1. mobile view
    https://github.com/WordPress/HelpHub/issues/235
    They agreed that it needs to change, so they are working on a template to be used by the entire WP.org ecosystem.
  2. anchor symbol
    They are thinking about using a similar treatment to GitHub. It will be global as well.

#needs-desing keywords for tickets

@estelaris added needs-design keyword to 3 trac tickets:

@estelaris will look into those 3 this week and will add screenshots

Improbements for archives

Docs Team did make some decisions on previous meeting that should improve usability of them

  1. Team agreed to use custom excerpts for each article – this is extra work for content but we can all help perhaps we can add another column to @atachibana ‘s document.
  2. Order of posts will be set manually because we want to make it contextual/complexity/step-by-step order
    This can’t really be automated and applicable to every category so we’ll use the order functionality in Post Attributes and @felipeelia already created patch for it.

Dev flow setup

@kenshino will catch up with @netweb.
@leogermani will test the documentation to get the dev environment up.

HelpHub rosetta release

Now, there are two releases: Serbian and Japanese.
Serbian team had HelpHub enabled on wrong site. It was disabled then and enabled on /support/ so they are ready to go.
Japanese team shared guide for getting started with this.

French, Brazil, Russia and some other countries are in the line for that activation.

HelpHub contents migration

@leogermani migrated content and hooks. Top 3 actions and filters (total of 6) were done and @millana_cap reviewed.

Open floor

@milana_cap suggested to have different people leading the meetings, Like rotating but more volunteering. We can call it a facilitator rather than “leading”. The agenda already mentions people sho will “lead” each topic.

@leogermani volunteered to lead the next HelpHub meeting, and @softservenet follows.

Agenda for HelpHub meeting 9 September 2019

Hello all,

The next HelpHub meeting will happen on

Monday, September 9, 2019, 15:00 UTC
  1. Attendance
  2. Content status @atachibana
  3. Design review – @estelaris
  4. Development (@milana_cap / @netweb)
  5. HelpHub rosetta release
  6. AOB

Helpful Links

Summary for HelpHub Meeting 26 August 2019

Attendance

@estelaris @kafleg @FahimMurshed @wizzard_ @softservenet @ibdz @felipeloureirosantos @justin @bph @kenshino @felipeelia @milana_cap @samikeijonen

Development

We discussed several issues today.

Excerpts on Archives

Last year it was proposed to replace auto generated excerpts with ToC list items. On today’s meeting discussion it’s been decided to use manually created excerpts which would contain the point of the article in one sentence. Short and concise. more meaning, less space.

Join discussion here: https://github.com/WordPress/HelpHub/issues/239

Posts Order on Archives

This was unsolved for a long time. We decided it’s important to order posts according to its content complexity so it resembles “Step 1, Step 2..” format or, if this doesn’t apply, to order according to post’s “importance”. As this is difficult to apply automatically to all categories we decided to use Post Attributes order and intentionally create order which we will specify in WP_Query.

As some articles have more than one category assigned, in which it might have different “importance” and order, we decided to make larger steps between posts using the same logic as menu items in dashboard. So two posts in a succession would have 10 places in between, rather than 1. This should also help with ordering articles published in the future.

Join discussion here: https://github.com/WordPress/HelpHub/issues/237

Single article mobile view

Viewing single article on smaller devices reveals the sidebar throughout the whole visible area. The rest of Handbooks solve this by hiding the sidebar altogether. @milana_cap suggested to place search form and single posts navigation instead of sidebar. For this single posts navigation to be useful, the order of posts (above) should be logical and intuitive.

@estelaris said that she’s working on templates and will discuss this issue on #design team meeting this Wednesday, as this is effecting all WordPress.org Handbooks.

Join discussion here: https://github.com/WordPress/HelpHub/issues/236

Design

@estelaris is working on overview of HelpHub design. Her analysis can be found in Google Spreadsheet: https://docs.google.com/spreadsheets/d/1ZnhtiLxqjXviFlnWsDE5L8YRiBXtkmanvM8doIc1lrg/edit?usp=sharing

After we agree on design template we need to have #accessibility review and usability test. @samikeijonen kindly accepted to perform these testings once we have everything ready.

Content and Rosetta Releases

We skipped these due to absence of key people.


Next Docs meeting is in #docs channel on

Monday, September 02, 2019, 15:00 UTC

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

Agenda for HelpHub meeting 26 August 2019

Hello all,

We have missed a few HelpHub meetings because of schedule and Slack downtime – the next HelpHub meeting will happen on

Monday, August 26, 2019, 15:00 UTC
  1. Attendance
  2. Development (@milana_cap / @clorith)
  3. Detailed content discussions
  4. Design
  5. HelpHub rosetta release
  6. AOB

Helpful Links

  • HelpHub Production – https://wordpress.org/support/
  • 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 HelpHub meeting – https://make.wordpress.org/docs/2019/06/18/summary-for-helphub-meeting-17-june-2019/

Summary for Docs Team Meeting 12 August 2019

Attendance

@kenshino @milana_cap @atachibana @clorith @David Curtiss @bph @leogermani @juliobox @softservenet @audrasjb @chrisvanpatten @clorith

Development

We are waiting for @netweb to finish setting up SVN and GIT repos together. Meanwhile @milana_cap started working on https://github.com/WordPress/HelpHub/issues/214 Once the new workflow is completed regular bug scrubs will be scheduled again.

Mobile view of HelpHub is identified as making HelpHub hard to use so we are going to prioritize those fixes if we don’t get the git + svn work done by this week.

Content

There are no requests for new pieces that we need to write. @atachibana volunteered to follow the state of Block Editor user’s docs as it is still hard to be found by people. @bph volunteered to help. They will reach out to @karmatosed regarding improvements.

We would like to have some input from Support Team on obvious gaps for Block Editor Docs. @clorith will bring this up on their next meeting.

@leogermani did half of remaining redirects and updated the spreadheet, expecting to finish everything by the end of the week. @audrasjb volunteered to help, @juliobox is already on it.

Design

Skipped due to missing reps.

Rosetta Releases

Japaneese release gathered 11 volunteers. Serbian rosetta still doesn’t have HelpHub enabled. @kenshino will ping @sergey about this.

Open Floor

We currently have 288 user notes (DevHub comments) in queue. @audrasjb volunteered to help with reviews. @softservenet will start a spreadsheet of Docs Team’s ongoing tasks and members working on them. 

Next Docs meeting is in #docs channel on

Monday, August 19, 2019, 15:00 UTC

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

#docs

Summary for HelpHub meeting 17 June 2019

Attendance

@nao @Pieter @chetan200891 @justinahinon @jeffmatson @makewebbetter @felipeelia

Phase 1.5 Development

@milana_cap Fixed

  • https://meta.trac.wordpress.org/ticket/4267

and waiting the merge

  • https://meta.trac.wordpress.org/ticket/4491

Still Open

  • https://meta.trac.wordpress.org/ticket/4492
  • https://meta.trac.wordpress.org/ticket/4493

If you want to tackle these issues, read below article at first to construct the development environment.
https://github.com/WordPress/HelpHub/blob/master/CONTRIBUTING.md

Phase 1.5 Design

@ibdz waiting for response on these:

  • https://github.com/WordPress/HelpHub/issues/245
  • https://github.com/WordPress/HelpHub/issues/246
  • https://github.com/WordPress/HelpHub/issues/201

Comment your thoughts to each issue. In WCEU, these items will be discussed with design team.

Contents Redirection

HelpHub migration and redirection were completed.
Next our goal is redirection of developer related pages such as Function, Class and Hooks.
Refer this article for step by step guide:
https://make.wordpress.org/docs/handbook/code-reference/editing-articles/

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

Docs team agenda plan in WCEU

  1. HelpHub in i18n (@nao)
    It should be collaboration of docs, polyglots and meta
  2. New Handbook plan for common programming topics (@atachibana)
    Refer this proposal:
    https://make.wordpress.org/docs/2019/05/19/proposal-wordpress-developer-handbook-for-common-topics/

Agenda for HelpHub meeting 17 June 2019

Hello all,

Next HelpHub meeting will happen on

Monday, June 17, 2019, 15:00 UTC
  1. Attendance
  2. Phase 1.5 Check-in
  3. Detailed content discussions
  4. Docs team agenda in WCEU
    • What items should we discuss?
  5. AOB

Helpful Links