Summary for Docs Team Meeting 18 November 2019


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



Notetaker & Facilitator selection

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


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.