Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Join our discussions of documentation issues here on the blog and on Slack.
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 accessibilityAccessibilityAccessibility (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:
Clear on purpose
Easy to read with keyboard
Reduce visual noise
Not polluting the link’s list for screen readers
# is it an anchor or a link?
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.
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 URLURLA 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>
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.
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
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.
Adding the link to the heading
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 WCAGWCAGWCAG 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.
The design above would be changed to meet the WordPress.orgWordPress.orgThe 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.
@leogermani says Last week we had less than 1% of hooksHooksIn WordPress theme and development, hooks are functions that can be applied to an action or a Filter in WordPress. Actions are functions performed when a certain event occurs in WordPress. Filters allow you to modify certain functions. Arguments used to hook both filters and actions look the same. redirected and now we have 2% \o/
@estelaris has been working on a new design to the support home page. There was a review with the design team and they would like to get rid of the grid and use a list instead.
The screenshot of the work in progress was shared in the related ticket: https://meta.trac.wordpress.org/ticket/4493#comment:8
Related tickets https://meta.trac.wordpress.org/ticket/4492 and https://meta.trac.wordpress.org/ticket/4491 were also updated and any feedback on the design can be given there.
we had @Jaap Wiering working on concept for adding AccessibilityAccessibilityAccessibility (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) notes and instructions where ever possible in DevHub and HelpHub
@milana_cap adds that with all the design changes being worked, it should be better to wait. @estelaris says that today #design and #accessibility teams should be free and I will get approval for both designs. “Will do my best to have them ready for development next week”
HelpHub rosetta release
@atachibana says “Japanese HelpHub migration does not have good progress ;-( 7 of 166 (4.2%) was done. We’ll encourage volunteers.”
@milana_cap says “Serbian team has momentum but then we’ve got it enabled on wrong website and waited for fix. It’s fixed now so I’ll make sure we start working on it this week. I’m trying to encourage others to lead the project”
@leogermani asked if there were any previous discussion on adding a “send feedback” or “inform error” button on the articles on HelpHub, to make it easier for people to contribute. Some people currently open tracTracTrac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. tickets or send messages in the slackSlackSlack is a Collaborative Group Chat Platform https://slack.com/. The WordPress community has its own Slack Channel at https://make.wordpress.org/chat/. channel directly.
Apparently there is not and he might open a trac ticket to discuss that.
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.
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 categoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. 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.
Viewing single article on smaller devices reveals the sidebarSidebarA sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. 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.orgWordPress.orgThe 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/ Handbooks.
@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.
Hello Docs folks. There’s a new project/set of docs that I think it makes sense for this group to be responsible for, but I want to get your input and see if there are any team members with a bit of a track record of responsibility who’d like to step up and take charge of it/them (someone who’s not already responsible for another big project).
As you probably know, the content on wordpress.tv (mostly WordCampWordCampWordCamps 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. videos, though starting to include other WP presentations and tutorials, all of which you are free to embed in docs) has not been captioned/transcribed. Adding captions/transcripts will make this content accessible to deaf and hard of hearing community members, will make it easier for someone to scan a video’s content, and will allow search engines to get a better index. As we introduce the ability to add caption files, these docs will need to be reviewed and managed.
Volunteers on this project should have good spelling/grammar skills so they can correct errors that captioning volunteers make, and should be willing to watch the videos on wordpress.tv to make sure the captioning volunteers did an accurate job.
The way it will work for now is that volunteers who want to contribute captions will do so on a third-party site (we’re recommending amara.org, but anything that lets you download a ttml file is fine). They’ll download the caption file (only the ttml format will work on wordpress.tv), then upload it to wordpress.tv through a form that will be available only to the vetted volunteers (at least for now).
Whoever steps up here will be a hero in the accessibilityAccessibilityAccessibility (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) effort, and will be responsible for wrangling captioning volunteers and ramping up new ones (eventually we should have some better docs and systems in place to require less hand-holding).
If anyone is interested in taking point on this, let’s hear it in the comments, and I can follow up with anyone who’s interested. We’re ready to launch this on Monday.
Note that members of the Accessibility group would participate in this effort under the aegis of the docs team, since docs is a product team, but accessibility is not. That said, someone from accessibility group who hasn’t participated in docs before also would be totally appropriate as the head volunteer.