First review on the new Sitemap for HelpHub

Following up on the post Explorations of a new classification for user documentation, we suggested to create 4 pillars (categories) and subcategories. My suggestion is to keep the subcategories to the minimum and add as many articles as needed, this will allow the system to grow as needed.

The 4 pillars in HelpHub

The 4 suggested pillars with their own subcategories are:

  1. WP Overview
    • About WordPress
    • Resources
    • FAQs
  2. Technical guides
    • WordPress installation
    • WordPress multisites
    • Configuration
    • Maintenance
    • Security
    • Troubleshooting
  3. Support guides
    • Get to know the dashboard
    • Publishing
    • Media
  4. Customization
    • Appearance
    • Default themes
    • Classic Editor
    • BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Editor
    • Common Blocks
    • Formatting
    • Layout elements
    • Theme Blocks
    • Widgets
    • Embeds

What has been done

During Google Season of Docs 2020, there was a project to reclassify all the articles, change article titles to follow the new style guide being written at the time and review the content (including links, outdated content, etc).

These are some of title changes given and the team will discuss the next steps to either change the affected URLs or not, but that is for another post.

Due to the rotation of contributors and the team focusing on other issues, the revision of content is still ongoing. If you would like to help out, join a meeting or reach out to @femkreations on WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/, @Femy on Slack and she will guide you.

The new titles and the reclassification has been done. We will continue to include articles that are still to be written, as well as any new article.

The first draft

This is a first draft of the Sitemap and we need your help to make sure articles are in the correct categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. or if there is anything else we need to add. You can leave your comments on this post or in the Draft of the Sitemap linked above.

What is up for review

  • Category names
  • Subcategory names
  • Articles classified in the correct category/subcategory

What is not for review

  • The four pillars (the title yes, but we won’t be adding anymore pillars)
  • Order of articles under categories nor order of subcategories (we will review them at a later time)
  • New name titles for articles (these were given during GSoD and have been already reviewed and accepted/rejected by the #docs team)

Other articles written as part of the redesign of HelpHub

If you would like to contribute or have any questions, reach out to @estelaris on Slack or leave a comment.

Props to @milana_cap for peer review.

#helphub

The hashtag and its future in documentation articles

In a previous post, we listed the requirements for the new design for HelpHub. This article is going to discuss one particular requirement, the hashtag at the end of the headlines inside an article.

Basically, we want to remove the # character from the headlines. It may be a radical change but it is necessary for accessibilityAccessibility Accessibility (commonly shortened to a11y) refers to the design of products, devices, services, or environments for people with disabilities. The concept of accessible design ensures both “direct access” (i.e. unassisted) and “indirect access” meaning compatibility with a person’s assistive technology (for example, computer screen readers). (https://en.wikipedia.org/wiki/Accessibility) reasons.

First of all, let’s mention the requirements to remove or replace the hashtag. The function must be:

  1. Clear on purpose
  2. Easy to read with keyboard
  3. Reduce visual noise
  4. Not polluting the link’s list for screen readers

The hashtag is used at the end of a headline in the articles as seen in the image below. In order to define its future, we need to understand its behavior.

Image of a headline including the hashtag

The hashtag is a link; the anchor is the H2 in the example above. It’s the anchor element, but it’s the link behavior, so it is ambiguous.

Technically, anchor refers to the target of an on-page link. This appears to be a link that gives easy access to identify the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org that will give you access to the current location on the document. That’s…actually kind of complicated.

What about accessibility?

The icon of the character used is not as important as communicating the function of the link. Right now, the # has aria-hidden=true label, so it won’t be read at all.

<h2 id="requirements-on-the-server-side" class="toc-heading" tabindex="-1">Requirements on the server side <a href="#requirements-on-the-server-side" class="anchor"><span aria-hidden="true">#</span><span class="screen-reader-text">Requirements on the server side</span></a></h2>

Link to the code page, line 196

It’s backed by screen reader text that duplicates the heading title, but is also nested inside the heading; this means that the heading text will be read  (e.g.) “Recommended setup Recommended setup”.  It’s creating duplicate text nested inside the heading and does not expose any visible text to explain the purpose.

The options

After some research, I have found several options for replacing and/or removing the hashtag.

  • Adding the link to the heading with a character
  • Making the heading a link
  • Replacing the hashtag with a fly-out menu

Adding the link to the heading, as used by GitHub,  where the link is currently the method to expose the link to that section. It can also be linked from the topics table, at the top of the article. We would have to make sure the implementation is accessible to others besides sighted mouse users.

The link element can be added at the beginning of the headline.
The link element can also be inserted at the end of the headline.

Adding the link to the heading is reasonable and the simplest solution to replace the hashtag, as it will simplify the problem: the functionality will be clear and the visual noise would be reduced considerably.

There are arguments against providing links that point to themselves, however, as it can make a confusing interaction. One of the arguments against this method is that it pollutes the link list on a screen reader. The way the hashtag is presented now, already pollutes the screen reader’s link list.

Replacing the hashtag

Replacing the hashtag with a fly-out menu, as explained by the w3.org. The w3.org recommends using the fly-out menu to meet WCAGWCAG WCAG is an acronym for Web Content Accessibility Guidelines. These guidelines are helping make sure the internet is accessible to all people no matter how they would need to access the internet (screen-reader, keyboard only, etc) https://www.w3.org/TR/WCAG21/.. The fly-out menu removes the need for multiple page loads. The biggest disadvantage is for people with reduced dexterity who can have trouble or it could be almost impossible to operate fly-out menus,which can be prevented with the correct implementation.


Video showing how the fly-out menu operates

The design above would be changed to meet the WordPress.orgWordPress.org The community site where WordPress code is created and shared by the users. This is where you can download the source code for WordPress core, plugins and themes as well as the central location for community conversations and organization. https://wordpress.org/ design style.

Removing the Symbol

Is removing the symbol entirely an option? Another recommendation from w3.org is placing the interactive elements in an order that follows sequence. This means adding a table of contents which will link to the interactive element, the headline in this case. Basically, the way it is right now but without the hashtag.

Video showing mouse-click to headline and the URL pointing to that headline

References

We would like to hear from you. Do you have another solution that could meet all the requirements?

Props to @ryokuhi, @joedolson, @milana_cap, @jillmugge for peer review.

Update 8 March 2022

We are moving the discussion to a meta ticket to discuss options and accessibility.

#accessibility, #docs, #helphub

Summary for Docs Team Meeting: January 27, 2020

Facilitator: @kulsumsiddique

Attendance: @kenshino, @bph, @felipeelia, @kulsumsiddique, @audrasjb, @ibdz, @wpza, @felipeloureirosantos, @nullbyte, @kafleg, @atachibana, @nobnob

Note-taker: @audrasjb

Next week Facilitator: @kenshino (but invite for other meeting facilitator is open, please comment below if interested)

Team workflow and badges

@felipeelia: workflow docs are being constructed on TrelloTrello Project management system using the concepts of boards and cards to organize tasks in a sane way. This is what the make.wordpress.com/marketing team uses for example: https://trello.com/b/8UGHVBu8/wp-marketing.. @milana_cap is the one to ask for access if needed.

Badges are being discussed in this P2 post. The contributor badge has been discussed for a while now, trying to reach a number of X micro contributions. On his last comment there, @felipeelia suggested to give the badge right away, just as in CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. and MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress.. @bph added that there is precedent on other teams and make the contributor badge seen right away: it’s the best onboarding tool we have.

@bph proposed a list of elligible contributions:

  • Fix an article
  • Create meeting notes
  • facilitate a meeting
  • reporting an issue on the comment form?
  • Creating a PR for GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/ docs
  • user notes on code reference
  • write an article on HelpHub
  • update an article on HelpHub
  • migrate a page to DevHub
  • Report an issues

@kenshino shared some worries about relevancy: “if we say that fixing a typo is fine – we’ll have a rush of requests to do that to farm badges”. Indeed, Core and Meta have automated system to give props to people who contribute on TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/., based on commit messages. There is no such system for Docs.

@felipeelia argued that 1) People receive core/meta badges sending a 1-line patch ; 2) Coming in to Docs SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. team and reporting a small typo does require some effort. @bph added that working out how to communicate a fix to the Docs team is a significant step. even if the contribution is just a typo fix. @kenshino agreed, but the team must keep an eye on abuse to tighten those rules if needed.

Regarding Team Badges, @kenshino proposed to set up a sheet and to give edit access to people that are running projects within the Docs Team.

HelpHub Survey

Reminder from previous meeting discussions: The goal is to build the questions of the survey with the general theme being “How do you think we can improve the WordPress documentation?”. Some questions using the likert scale to track how good it is now so the Team can repeat the survey in the future. Some open fields to get proper feedback so it’s possible to define future projects better. That would be great for this survey to be ready for WordCampWordCamp WordCamps are casual, locally-organized conferences covering everything related to WordPress. They're one of the places where the WordPress community comes together to teach one another what they’ve learned throughout the year and share the joy. Learn more. Asia, in less than one month.

@atachibana is coordinating the effort. @bph proposed to assist on this task.

Step 1 is to start a Google Doc in the team’s shared folder.

This survey and the Docs team focus for WordCamp Asia are set to be the next meeting focus.

@bph proposed to draft a P2P2 P2 or O2 is the term people use to refer to the Make WordPress blog. It can be found at https://make.wordpress.org/. post to ask for questions proposals. @kenshino proposed to review this draft.

#contributor-day, #helphub

Docs Chat Agenda – July 14, 2016

Here’s the agenda for the Docs team weekly chat, which are held Thursdays at 17:00 UTC in the #docs channel on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/..

Current Projects Updates:

  1. Theme Developer Handbook – @kenshino
  2. Codex MigrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. (DevHub) – @drewapicture
  3. DevHub – @drewapicture
  4. HelpHub – @kenshino
  5. Inline Docs – @drewapicture

Other Stuff:

  1. Internationalizing documentation
  2. Version articles (HelpHub)
  3. Hosted about pages
  4. Open Floor

#chat, #codex-migration, #handbooks, #helphub

Agenda for Helphub Meeting 24 May

Time/date: Tuesday, March 15, 2016, 14:00 UTC in #docs

Pinging @nlarnold1 @psykro @sarassassin @justingreerbbi @greensteph @rachelwhitton @jayhoffmann @carlalberto @geoffreyshilling @atachibana @jasonpomerleau @sumeet @bellaratmelia @pansotdev @normalize @ankitguptaindia @mikevanlohuizen @ramiy

If you’re helping, have helped or volunteered to help with Helphub, I’m pinging you to bring you back to the fold

Agenda

  • Status Updates
  • Overlaps with Theme Handbook and how we will handle it
  • Open Floor

#agenda, #helphub

Summary for Helphub Meeting 17 May

Attendance

@greensteph @justingreerbbi @hardeepasrani @carlalberto @Kenshino

General Progress

I’m charting our progress against an online gantt chart so feel free to help out in any of the processes that are not at 100%. Especially the article rewriting ones!

Search Function and Search Templates

@justingreerbbi has auto complete working and wants some help on deciding what datasets to query to throw inside the auto complete. The search bar dropdown is intended to be modelled against Amazon’s search function.

We believe that people require real suggestions when they do search.

@carlalberto and @justingreerbbi will be collaborating on the styling

Frontpage Templates

@carlalberto will be working on it

Unique Articles that may need help fitting into Helphub

The WordPress Versions articles is an example of a complex article that has relationships to it’s sub articles. Maintaining it may require more than just posts as each version comes with a changelog and a blog post tied to it with other metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. data.

The team should be on the lookout for any other unique articles that does not naturally fit into our post templates

Release

We are still hoping to release the first iteration of Helphub in July / August so let’s keep it up!

Help Needed

We still need a lot of help to complete this project. Drop us a line at #docs or send me a direct message (@kenshino)

Read the meeting transcript in the Slack archives. (A Slack account is required)

#helphub, #summary

HelpHub Meeting: Mar. 15

Reminder about our weekly HelpHub meeting at 14:00 UTC today. We’ll be looking over some of the recent development and discussing any potential issues.

Time/date: Tuesday, March 15, 2016, 14:00 UTC in #docs

#agenda, #helphub

HelpHub Meeting: Mar. 8

I’m back for the HelpHub meeting this week, so let’s run through a status update and see what we all need assistance with.

Time/date: Tuesday, March 8, 2016, 14:00 UTC in #docs

#agenda, #helphub

HelpHub Meeting Agenda: Mar. 1

I won’t be able to attend the HelpHub meeting today, but @kenshino will be leading the meeting in my absence. This meeting is largely a status update and a discussion about any issues that arise from that, so please keep it focussed and reserve any specific, lengthy topics for after the meeting. I’ll catch up on the back scroll tomorrow and supply any feedback where necessary.

Time/date: Tuesday, March 1, 2016, 14:00 UTC in #docs

Agenda:

  1. Status update
    • Let’s get the latest status update on development and content migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies..

#agenda, #helphub

Contributing to HelpHub

We’re at the stage right now with the HelpHub project where we are able to accommodate contributors more easily as well as have tasks for Contributor Days.

If you would like to contribute to HelpHub, then have a look through this guide: https://make.wordpress.org/docs/handbook/about-the-docs-team/current-docs-projects/helphub/ – the primary need right now is for people to get involved in migrating content from the Codex over to the HelpHub staging site.

If you have questions or want to know more about how you can work with HelpHub at your Contributor DayContributor Day Contributor Days are standalone days, frequently held before or after WordCamps but they can also happen at any time. They are events where people get together to work on various areas of https://make.wordpress.org/ There are many teams that people can participate in, each with a different focus. https://2017.us.wordcamp.org/contributor-day/ https://make.wordpress.org/support/handbook/getting-started/getting-started-at-a-contributor-day/. then feel free to pingPing The act of sending a very small amount of data to an end point. Ping is used in computer science to illicit a response from a target server to test it’s connection. Ping is also a term used by Slack users to @ someone or send them a direct message (DM). Users might say something along the lines of “Ping me when the meeting starts.” me on SlackSlack Slack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/..

#contributors, #helphub, #status