Summary of Docs Team Meeting April 19, 2022

Housekeeping

Review of the design for documentation 

The design team has reviewed the design. We are waiting on Josepha’s approval. The mobile version is not ready yet as there are a few items to be resolved. 

  • We now have 4 categories for the content and a submenu with the 4 categories, displayed at the top so users can easily navigate. 
  • The breadcrumbs are included as part of the left navigation (the blue square on the top left). The first 3 lines are the breadcrumbs, followed by the headings in the article. We also have another option (on the 3rd article example) where the breadcrumbs are horizontal, at the top of the TOC 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..

Please add your comments here or in the slack channel.

Discussion 1: @femkreations: How are we handling the Changelog section since some of the Changelog entries are long?

@milana_cap: suggests not to delete the Changelog as it’s a history of the WP docs.
@bph: The Changelog is also used for translation and some locales might be behind on the pages.
@ibdz: We can have 2 different font sizes- one for the parent <li> (date) and one for secondary level <li> (content) to keep it aesthetically pleasing.

It was decided to add pagination to the Changelog. It is accessible and we can limit the number of entries per page, keeping the newest entries on page one and the oldest on page 2.

Discussion 2: @milana_cap: Would the definition list be semantic markup for the Changelog?

 @mburridge suggests the details disclosure element

Discussion 3: @estelaris: What about the FAQs that are on some of the block articles? Are we going to keep them there or can we extract them and create a new FAQs section under resources?

@milana_cap: Thinks all FAQs should be in FAQs and articles that currently have them could link to them.
@atachibana: Suggests keeping it as is, to reduce the cost, and also create independent pages of the FAQ.
@ibdz: Thinks from the user’s point of view, it’s good to have the FAQ attached to the page.

Project updates

@milana_cap:

  • Closed a few more 5.9 block editor end-user issues.
  • All tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/. tickets are labeled for docs and GitHub project is ready.
  • We have a new channel #docs-firehose for getting 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/ updates so that we keep the #docs channel clean

@femkreations:

  • Triaging the Google Doc and creating the Tracker issues for 6.0 end-user documentation.
  • So far, 40 trackers have been added for 6.0 End User Documentation.
  • Will complete the triage by the end of the week.

@estelaris:

All the block editor articles listed in the inventory have been added to the new sitemap.

Open floor

@estelaris and @femkreations to review the following two pages: Block Editor and WordPress Editor to make sure they are not repetitive and if so, merge and delete one. @atachibana: Suggests renaming WordPress Editor to Classic Editor and keeping with TinyMCE.

@milana_cap gave a talk about Docs at 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. Athens in person.

@milana_cap to lead the Docs table at the 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/. for WCEU.

#meeting

Season of Docs 2020 Projects Move Forward

Google recently announced that two of our Season of Docs 2020 projects are moving forward:

  • Documentation Style Guide proposed by Jon Ang (@kenshino)
  • Improving Article Discovery proposed by Estela Rueda (@estelaris)

These were two of nine possible Docs team projects proposed to GSOD technical writers for vetting.

We arrive at this happy moment after four months of ongoing process and collaboration. Considering there were 49 other organizations participating in Google Season of Docs 2020, it’s a credit to our community effort to bring dedicated technical writers to both projects.

Docs team contributor Atharva Dhekne (@tacitonic) is the technical writer for the Documentation Style Guide project. Milana Cap (@milana_cap) and Felipe Elia (@felipeelia) will be the project mentors.

For Improving Article Discovery, we welcome Diana Mivelli (@dmivelli) as the project’s technical writer. Project author Estela Rueda and (author of this post) Tim O’Haver (@timohaver) will be the project mentors.

Near term, the Season of Docs timeline allows for our writers to get acclimated. By middle September, Atharva and Diana will be fully engaged in their documentation work through November.

#season-of-docs

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

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

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.

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!

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

Agenda for Documentation Team Meeting September 28, 2021

The next meeting is scheduled with the following details:

When: Tuesday, September 28, 2021, 14:00 UTC

Where: #docs channel on Slack

Meeting Agenda:

  1. Project Updates
  2. 15 min repo triage/ If needed
  3. Open Floor

Please feel free to suggest agenda items by commenting on this post or raising it during Open Floor.

Thank you!

[Announcement] New workflow for reporting documentation issues

For a few weeks now Documentation team is testing out new workflow for reporting issues – a GitHub repository which will be a single, centralised place for reporting all documentation issues. How and why we decided to do this can be found in team’s meeting notes.

What we hope to achieve with this workflow:

  • Easier contribution in form of reporting issues – even though this workflow still requires another account from contributor (the 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/ one), with this workflow contributor doesn’t need to know which part of documentation is issue for. They can just report the issue and move on, if they so wish. We lost many one-time contributions due to the complicated workflow for reporting issues.
  • Easier contribution in form of fixing issues – with all projects and their different reporting issues tools, contributor who wanted to join team and work on fixing issues had to decide which project they wanted to work on before even seeing issues. With everything in one place they can browse all the issues, find the ones that seem interesting and then look for advice on fixing it.
  • Some projects didn’t have any way for reporting issues except for coming 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/. channel and hoping that someone will see it. This way is deprived of a place where the issue would be discussed as many things get lost in Slack noise. Also, this way is almost impossible to keep track of contributors and give them credits for their contributions.
  • Easier managing of projects and documentation in whole – team members have better overview of everything that’s happening in every Docs project, can help out in projects they usually don’t work on and have a general picture of WordPress documentation as a whole.
  • Easier contributions tracking – with every issue, comment, contribution being saved in one place, we have a better understanding of how certain parts of docs were created and who worked on them.
  • Better planning and setting goals with GitHub projects.
  • Better understating and following progress and statistics for each project by structured labeling system.
GitHub issue discussion.
GitHub issue discussion

We are still configuring labels, templates and the repo itself; and still figuring out the best way to work on/with issues. For the future we hope to connect this repository with the actual documentation at 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/ so that contributions can be make directly on the page with the issue which would automatically create new issue and apply proper labels.

In the next phase, which will be soon, we will start using GitHub Projects for managing all the issues.

GitHub Project board for managing all GitHub issues from the repository.
GitHub Projects board

Documentation Team is managing all documentation as an unified project and is adopting appropriate tools in order to do so.

As always, if you have any questions or suggestions, please leave the in comments bellow.