Welcome to the official home of the WordPress documentation team.
This team is responsible for coordinating all documentation initiatives around WordPress, including the Codex (moving to HelpHub and DevHub), handbooks, parts of developer.wordpress.org, admin help, inline docs, and other general wordsmithing across the WordPress project.
Want to get involved?
There are many ways in which you can help the Docs team. Every small contribution counts and helps! You can report an issue or typo you found in the docs, or even help us write new documentation for parts that are still missing. These are some helpful links to find out more about what we do and how to collaborate:
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 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.
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 URL 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.
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
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
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 WCAG. 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.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
@estelaris worked on updating terms in the glossary. The overview is on a GitHub project so we can keep track of the new words we are updating.
A couple of terms are not yet in there, as we are waiting for clarification from @annezazu.
Global Styles to be changed to Styles as per the new language we are following.
@estelaris to open an issue seeking an explanation for the difference between Block Styles, Local Styles, and Global Styles
Create HelpHub Block Editor articles list:
@milana_cap proposed creating a list of all the HelpHub block editor articles for managing future updates.
@bph had a google spreadsheet with the list of articles. @milana_cap suggested it would be a good idea to have the contents of this list in GitHub.
@femkreations proposed creating a GitHub Project with the list of articles and volunteered to create the project and move the contents from the spreadsheet into the Project.
A full transcript can be found in the #docs channel in the Making WordPress Slack
HelpHub content
thanks to @annezazu, HelpHub is getting new pages relating to V5.9. Those pages will be translated via #polyglots team.
@atachibana highlighted the need for auto-changelog – this is a topic for future discussion.
future plans: re-design of HelpHub, adding TOC or index into side bar area – however global design changes are coming.
Block editor end user docs
currently without lead in case anyone wants to volunteer.
a large amount of work is still outstanding here, tasks need to be moved from Trello to GitHub while filtering out what’s no longer relevant and keeping what is still relevant.
@milana_cap will start working on that this week and allocate some time each week until a new lead volunteers to own the project and can then continue the work themselves.
block themes and classic themes have been separated in the developer handbook menu, which will make it easier for those who want to find resources for the two separate theme types.
in addition, some typos, old links, and other minor things have been updated.
@milana_cap asked whether there is any content on converting a classic theme into a block based theme, but @kafleg reports that content on block themes has not been started on yet. There are, however, plans to create a list of topics.
@atachibana emphasised the need for a page on creating a Child Theme from a Block Theme.
there’s a requirement to go through this handbook and see what’s missing/outdated/etc…
Onboarding
@sukafia acknowledges that this has been on hold for a while. Previous work will be reviewed and next steps decided on.
Coffee breaks
@sukafia acknowledges that this has been on hold for a while. Previous work will be reviewed and next steps decided on.
Design
WP.org is getting a full redesign, @estelaris now has access to the style guide and will change the previous design of HelpHub and hopes to present the new redesign at WCEU.
The following projects were not addressed, either because the lead was not present or because we ran out of time.
We met to discuss the upcoming block themes in WP 5.9 and where to document with relation to the existing Theme handbook.
Summary:
Block themes has a small call out as an experimental feature now on the first page of the Theme handbook. The next step is to update that page with a clear distinction between Classic themes and Block themes, a brief explanation about the differences, and links to learn about each. Classic themes links will continue to theme handbook, Block theme links will go to Block editor handbook.
Discussion:
We discussed what current documentation we have between the two handbooks. The ongoing goal will be to highlight the areas of overlap between classic and block themes and keep those in the handbook, try not to duplicate any documentation in either handbook, and use plenty of cross links so developers can find what they need.
We touched on some complexities with the Block editor handbook structure. The initial goal was teaching developers about blocks, getting them started learning and creating blocks. We need to look at information architecture and flow of the handbook to better help developers navigate. For with WP 5.9 features like block themes, theme.json, styles and settings a developer can be greatly involved with topics covered in the handbook without having to create a block.
A larger project that needs to be tackled is the information architecture of all developer handbooks and documentation. Valuable content is being created and organized in various different areas in different ways, this makes it hard for developers to find what they need. For example, great developer content is created within Learn that is not cross-linked with developer.wordpress.org. Additionally, browsing the “Common API” or “Code Reference” sections only return the PHP APIs when there is a large suite of JavaScript APIs in the Block editor handbook.
