Milana Cap 7:23 pm on March 8, 2022
Tags:   

Summary of Docs Team Meeting March 8, 2022

Housekeeping

Project updates

Docs issue tracker

Updates for issues repo in last 7 days: https://make.wordpress.org/updates/2022/03/07/documentation-team-update-march-7-2022/

WordPress 6.0 release

Docs focus team for WordPress 6.0 release had a first meeting yesterday. If anyone likes to join, help with writing parts of docs, just watch the process, get involved in whatever form, you can do so by stating your interest in #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/. channel or pinging @milana_cap (zzap in slack).

Everyone is welcome to join #6-0-release-leads; you might not be able to post but you’ll see the process and what’s happening.

End user 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 docs

General end user docs

  • new sitemap – @estelaris wrote First review on the new Sitemap for HelpHub and needs feedback on it.
  • replacing hashtag – @estelaris opened ticket with #meta for evaluating 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) issues and design for removing the hashtag https://meta.trac.wordpress.org/ticket/6171

Developer docs

  • technical parts removed from HelpHub – @femkreations created a GH Projects that has the inventory of the technical parts that are removed from the end user docs https://github.com/orgs/WordPress/projects/26/views/1. It’s a work in progress. If you’d like to help, 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.” @femkreations (Femy in slack).

Needs feedback

  • First review on the new Sitemap for HelpHub – one of discussion questions – should FAQ articles live separately in FAQ category or be in their respective sections
  • Change article titles part 1 – it was recommended from Marketing team (@jonoaldersonwp) to change URLs as well and use 301 redirects – we have to ask in 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. for options to do this.
  • URLs for new HelpHub articles – we don’t have anything about this in Style Guide and @femkreations needs directions for those missing articles in 5.9. Proposed solution is to follow consistency where possible (e.g. adding -block for block articles and embed- for embed blocks) and leave other slugs to be created naturally from the title.

#summary

TC 1:58 pm on March 8, 2022
Tags: , ,   

Agenda for docs team bi-weekly meeting 8 March 2022

The next meeting is scheduled with the following details:

When: Tuesday, March 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

@femkreations has the floor

For the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org for the new pages in the HelpHub, is there anything specific to keep in mind while creating the URL?

@estelaris has the floor

Reviewing the re-categorization and renaming of some articles.

4. Open floor

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

#agenda, #meeting-agenda, #meetings

Estela Rueda 5:52 pm on March 7, 2022
Tags: ,   

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

Femy Praseeth 2:42 am on March 2, 2022
Tags:   

Summary of Docs Team Meeting Feb 22, 2022

Housekeeping

Project updates

@milana_cap:  Updated the following 2 articles to 5.9.

The future of the hashtag in documentation articles

@estelaris: Please read the post about the hashtag, and share your comments and questions. The 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) team supports any of the ideas in the post. She will be discussing further with the 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. team. The post has been flagged to Josepha for Matt’s attention as we need his approval to apply any of the solutions.

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 doc pages inventory on GH projects

@femkreations:  The inventory for the block editor end-user docs is ready in GH Projects. She will open new trackers for the 56 pages that are missing in HelpHub based on the inventory.

Adding tips section to docs

@milana_cap: We are deciding whether we want to offer “best practices” kind of advice to docs. These best practices would not be our personal opinions, but ones collected from dev notes, other teams, opinions of the majority/most experienced, and a general guide of what works. 

ACTION ITEM: @milana_cap to write 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/. to discuss this further and get opinions from other teams. 

Some things to consider: Whose opinions should be considered for making the best practices and what happens if they disagree?

Best practices to handle GH tickets (who to contact when you have issues/questions when documenting):

This item came up as a contributor posted in the #docs channel on Slack that he was having issues with screenshots quality and his comment went unanswered.

ACTION ITEM: We could add a list of team reps’ names in CONTRIBUTING.md maybe in the issues template.

Question by @mitchblue006: For this issue, when creating screenshots is it ok to use a dummy account?

@milana_cap: As long as it is the correct WordPress version, fresh install with no additional plugins, no themes or languages changed, dummy account is fine

She also shared this awesome app https://app.instawp.io/login. You can choose 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. and WP versions and the installation lives for 72 hours, after which you can revive it and the content will be preserved.

Documenting best practices and rules

Based on a discussion started here, which code standard should code samples adhere to?

@themiked: the answer was WordPress-CoreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. but WordPress-Extra is better. He re-visited every page in the 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 and fixed the code samples to be compliant.

@milana_cap: For plugin/theme development you should really compile to WordPress Coding StandardsWordPress Coding Standards A collection of PHP_CodeSniffer rules (sniffs) to validate code developed for WordPress. It ensures code quality and adherence to coding conventions, especially the official standards for WordPress Core.. We need to present the code in docs by WordPress-Extra coding standards. This is applicable mainly for the docs maintainers.

@estelaris: Do we need to add this tip somewhere so all contributors are aware of it?

Open Floor:

Discussion 1: 

@femkreations: Related to this tracker – removing the technical content from the HelpHub where will the removed technical parts go, as she starts making the updates to end user docs? 

@milana_cap: They will go into some/few of devhub handbooks, depending on the topic.

ACTION ITEM: @femkreations to create a GH project to track the removed technical parts- where they came from and an open column that tracks where they are going.

Discussion 2:

@milana_cap: To revive docs team coffee breaks, and use it partly as onboarding calls if new contributors like to join. We will try them for a couple of months and see results.

ACTION ITEM: @milana_cap to set up a doodle to start.

#meetings

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.

Update 8 March 2022

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

#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!