Courtney Robertson 10:54 pm on February 25, 2022
Tags: ,   

X-post: Proposal to Start a News blog on developer.WordPress.org

X-comment from +make.wordpress.org/core: Comment on Proposal to Start a News blog on developer.WordPress.org

Estela Rueda 2:36 pm on February 21, 2022
Tags:   

Agenda for docs team bi-weekly meeting 22 February 2022

The next meeting is scheduled with the following details:

When: Tuesday, February 22, 2022, 03:00 PM GMT+1

Where: #docs channel on Slack

Agenda

  1. Attendance
  2. Note-taker & Facilitator selection for Next Meeting
  3. Projects checks
  4. Best practices to handle GH tickets (who to contact when you are stuck, screenshots, etc)
  5. Documenting best practices and rules – discussion
  6. Open floor

If there’s anything you’d like to discuss in open floor, please leave the comment below.

#agenda, #meetings

#meeting-agenda

Estela Rueda 7:31 pm on February 20, 2022
Tags: , ,   

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.

#accessibility, #docs, #helphub

Femy Praseeth 10:00 pm on February 8, 2022  

Summary of Docs Team Meeting Feb 8, 2022

Housekeeping

  • Next Meeting: Tuesday, 22 February 2022
  • Next Meeting Facilitator: @estelaris

Project Updates

Yoast 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/.: 

The Documentation table was led by @milana_cap. 

The following people worked ​​on updating the 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 end user docs for 5.9 and made good progress: @mikes41720 @jaz_on @agnieszkaszuba @hannaw93 @darkavenger @nilovelez @mrkdevelopment

@milana_cap worked on migrating issues from 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. to GitHubGitHub GitHub is a website that offers online implementation of git repositories that can 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/ and reviewing what’s been done.

If anyone wants to work on the block editor end-user docs, here are the open issues: https://github.com/WordPress/Documentation-Issue-Tracker/projects/3

WordPress Glossary:

@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.

TC 1:40 pm on February 8, 2022  

Agenda for docs team bi-weekly meeting 8 February 2022

The next meeting is scheduled with the following details:

When: Tuesday, February 8, 2022, 03:00 PM GMT+1

Where: #docs channel on Slack

Agenda

1. Attendance

2. Note-taker & Facilitator selection for Next Meeting

3. Projects checks

4. Open floor

If there’s anything you’d like to discuss in open floor, please leave the comment below.

#agenda, #meetings

Akira Tachibana 3:43 pm on January 25, 2022
Tags:   

Summary of Docs Team Meeting Jan 25, 2022

Attendance

@estelaris, @kafleg, @milana_cap, @atachibana, @femkreations, TC, @kenshino, @themiked

Housekeeping

Project Updates

A full transcript can be found in the #docs channel in the Making WordPress 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/.

HelpHub page titles and urls

In the future, we should be able to be able to change page titles/urls /301s. For more detail refer this discussion and @estelaris‘ two tickets:

Now, we should keep current page titles and urls.

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. EU 2-4 June

@milana_cap will lead the Documentation Team at Contributor Day.

Do contribution and get a cookie!

Estela Rueda 2:59 pm on January 24, 2022  

Agenda for docs team bi-weekly meeting 25 January 2022

The next meeting is scheduled with the following details:

When: Tuesday, January 25, 2022, 03:00 PM GMT+1

Where: #docs channel on Slack

Agenda

1. Attendance

2. Note-taker & Facilitator selection for Next Meeting

3. Projects checks

  • WP releases – currently 5.9 – @mkaz
  • HelpHub content – @atachibana
  • 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 end user docs – currently without lead
  • HelpHub feedback curating – currently without lead
  • PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party handbook – @themiked
  • Theme handbook – @kafleg, @utz119, @poena
  • Common APIs handbook – @leogermani
  • Block editor dev handbook – @mkaz
  • Reference handbook – more info – @juliobox
  • Reference handbook – curating user contributed notes – @audrasjb, @crstauf
  • Docs team handbook – @milana_cap, @atachibana
  • Onboarding – @sukafia
  • Coffee breaks – @sukafia
  • Design – @estelaris
  • Docs style guide – applying – @tacitonic
  • External linking policy – @milana_cap and @themiked for Plugin Handbook
  • Docs issue tracker – have we started fixing reported issues?

4. Open floor

If there’s anything you’d like to discuss in open floor, please leave the comment below.

#agenda, #meetings

Michael Burridge 2:45 pm on January 12, 2022
Tags:   

Summary of Docs Team Meeting Jan 11, 2022

Attendance

@milana_cap, @daisyo, @atachibana, @kafleg, @mburridge, @estelaris, @jdy68, @wizzard_, @utz119, @juanmaguitar, @mitchblue006, @femkreations, @kenshino, @sukafia

Housekeeping

Project Updates

A full transcript can be found in the #docs channel in the Making WordPress 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/.

  • 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.
  • 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 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 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. to GitHubGitHub GitHub is a website that offers online implementation of git repositories that can 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/ 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.
    • @atachibana will also help with this.
    • @jdy68 expressed interest in helping.
  • HelpHub feedback curating
    • currently without lead in case anyone wants to volunteer.
    • comments are coming in but someone is needed to curate them, filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. out the spam and support and move the relevant ones to GitHub.
    • @esteleris has been helping out.
    • if anyone wants to be responsible for managing these comments, @milana_cap is willing to explain everything in detail.
  • PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party handbook
    • future plans: needs to be updated with the style guide.
    • it has been “blockified” already but still needs external linking.
    • @themiked plans to create a plugin which will form the basis for a progressive tutorial – this is still in the preliminary stages.
  • Theme handbook
    • 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.
  • Common APIs handbook
    • @milana_cap stated that she has ideas for this one and will create a GitHub issue for it.
  • Reference handbook – curating user contributed notes
    • there are currently 38 pending comments.
    • please 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.” @milana_cap  if help is needed on this.
  • Docs team handbook
    • 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.

Would the leads of those project please reply in comments on the agenda, thanks.

Milana Cap 9:56 am on January 11, 2022
Tags: ,   

Agenda for Docs team bi-weekly meeting January 11th, 2022

The next meeting is scheduled with the following details:

When: Tuesday, January 11, 2022, 14:00 UTC

Where: #docs channel on Slack

Agenda

1. Attendance

2. Note-taker & Facilitator selection for Next Meeting

3. Projects checks – current status, where we need more people (some need reps as well).

  • WP releases – currently 5.9 – @mkaz
  • HelpHub content – @atachibana
  • 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 end user docs – currently without lead
  • HelpHub feedback curating – currently without lead
  • PluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party handbook – @themiked
  • Theme handbook – @kafleg, @utz119, @poena
  • Common APIs handbook – @leogermani
  • Block editor dev handbook – @mkaz
  • Reference handbook – more info – @juliobox
  • Reference handbook – curating user contributed notes – @audrasjb, @crstauf
  • Docs team handbook – @milana_cap, @atachibana
  • Onboarding – @sukafia
  • Coffee breaks – @sukafia
  • Design – @estelaris
  • Docs style guide – applying – @tacitonic
  • External linking policy – @milana_cap and @themiked for Plugin Handbook
  • Docs issue tracker – have we started fixing reported issues?

4. Open floor

If there’s anything you’d like to discuss in open floor, please leave the comment below.

#agenda, #meetings

Marcus Kazmierczak 6:59 pm on December 8, 2021  

Meeting Notes: Theme docs updates for WP 5.9 and block themes

Who: @milana_cap, @mkaz, @utz119

When: Dec 8, 2021 @ 1500 UTC

What:

We met to discuss the upcoming 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. 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.jsonJSON JSON, or JavaScript Object Notation, is a minimal, readable format for structuring data. It is used primarily to transmit data between a server and web application, as an alternative to XML., 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.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/. Additionally, browsing the “Common APIAPI An API or Application Programming Interface is a software intermediary that allows programs to interact with each other and share data in limited, clearly defined ways.” or “Code Reference” sections only return the PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. APIs when there is a large suite of JavaScriptJavaScript JavaScript or JS is an object-oriented computer programming language commonly used to create interactive effects within web browsers. WordPress makes extensive use of JS for a better user experience. While PHP is executed on the server, JS executes within a user’s browser. https://www.javascript.com/. APIs in the Block editor handbook.

+make.wordpress.org/themes/