Summary for Docs Team Meeting on 21 September 2020

Attendance

@justinahinon, @dianamivelli, @estelaris, @kartiks16, @tacitonic, @chaion07, @atachibana, @sukafia, @bobbingwide, @kulsumsiddique, @mkaz.

Thanks to @estelaris for Facilitating the Meeting.

Notetaker & Facilitator Selection

Notetaker: We could use a few volunteers to take notes for our weekly meetings. If you want to help then please comment here or let us know during our meetings.

Facilitator for the next meeting: @chaion07

Next Meeting: 28 September 2020

Find the complete Transcript of the meeting on 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/..

Project Updates

@milana_cap updated badges page with a new document and a process for tracking contributions. (asynch to the meeting)

@atachibana reported on the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. and re-routing of Codex to Code:

  • 29 Classes out 43 have been completed which is an improvement of 7.4% leading to 67.4% from last week’s 60.5%, and
  • 51 HooksHooks In 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. out of 355 have been completed which is an improvement of 2.6% leading to 14.4% from last week’s 11.8%.
  • @atachibana thanked @stevenlinx for the contribution.
  • He also did some housekeeping on Codex this week and welcomed suggestions from everyone.

@bph also provided an update beforehand on Digital check in for 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 Documentation (BEE-docs). Birgit requested that the BEE-docs team members leave comments on that post. (async to the meeting)

Docs Videos

@milana_cap fully recorded a contributing video and forgot to silent nearby devices and as a result there were a lot of background noises in the recording. Eventually had to delete it and she’ll attempt to re-record it. (async to the meeting)

External Linking Policy

@milana_cap reported prior to the meeting that the team started with the Plugin Developer Handbook for the discussion on External Linking Policy. @themiked outlined two phases. Please let Milana know if help is needed with this. We want to make the entire process transparent and publish on our blog. It’ll also help with defining the workflow for the other parts of #docs.

@themiked also reported that the goal is to compile a list of all the links on all the pages 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 guide and start with that, hopefully deleting them all and then adding back the ones on the approved domain list (asynch to the meeting).

New Member Mentoring Team

Due to everyone’s commitments, the Mentoring Team isn’t being able to properly focus on the Mentoring process for the past few weeks. The team is looking for new people to join over Making WordPress #docs team.

Please contact @sukafia, @softservenet, @tacitonic or @Prubhtej_9 with your ideas, suggestions and comments (if any).

Monthly Coffee Break Reminder (September 2020)

@sukafia provided the team with the schedule for the Monthly Coffee Break for September 2020.

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.” @sukafia or @chaion07 if you require further assistance.

Google Season of Docs

@tacitonic reported:

  • Working Repository has been transferred to the WordPress organization on 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/.
  • Almost done with the first section. You can read more about it here: https://github.com/WordPress/WordPress-Documentation-Style-Guide/tree/master/docs/2-document-guidelines (Overall status: one week ahead of schedule).
  • Waiting for a confirmation from the #docs team for a suitable location for the Style Guide 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/ for a request that was made on the 15th of September

@dianamivelli reported:

  • Been reading HelpHub topics, making sure the titles are applicable, and suggesting new titles for some.
  • Raised the topic of identifying a consistent title style such as action+object for the title, when possible.
  • Further discussion is being done on a private Slack channel consisting folks from the #docs team that @estelaris had opened.

@estelaris added:

  • The Slack group includes both Technical Writers and all four mentors to discuss any topic that relates to both projects, as we will coincide in certain points and it is good to agree on the best approaches.
  • The big topic discussed this week was ‘Article Titles’. Removing Gerunds and adding an action+object title.
  • Also discussed the use of one-word titles.

The Technical Writers will be following the Handbook Grammar Guide as always. Thanks to @atachibana for sharing the link.

Open Floor

@bobbingwide asked if WordPress documentation could be kept up to date with the latest release? @estelaris answered that it would be really nice and the team is working hard to reach that goal. But since we had to migrate the articles from one site to another, we are taking the time to also update those articles. Another team is working on a new design for the pages. The Google Season of Docs Team is working on a new writing style guide and a new classification to implement a new navigation to documentation. There is also the Release Team who is working on adding documentation on the new releases. Not to mention the typos, broken links, small updates, etc that need constant upkeep.  With too many moving parts the team is working very hard and will reach our goal of having up-to-date, easy to find documentation soon.

@bobbingwide further asked, How committed is the Release Team to delivering the documentation for the new release concurrently with the new release? @joyously advised this question to be addressed in the Dev Chat and the editor in particular should be documented before being incorporated into coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress..

@bobbingwide also asked on the point of view of the docs team? @estelaris replied saying that the Release Team is very committed particularly to work on that and documentation needs to be ready before the public release.@mkaz added by saying there shouldn’t be a #docs team, that function should be a part of every feature development and those features shouldn’t be merged/released without documentation. @estelaris also shared the link to the 2020 WordPress Release Squad and another link to the WordPress 5.6 Release Planning @makz added by saying that it should be more integrated into the development of the features- if something doesn’t get merged without documentation, then you wouldn’t need a documentation squad for the release, by default it would be there.@justinahinon added async to the meeting by saying that one of the roles of the Release Documentation Team is to ensure that new things that come in the release receive proper documentation. So approximately 90% (estimation), new stuff in a release are documented by the date of the release. @estelaris invited @bobbingwide to attend the Dev Chats in the #core channel on Wednesdays at 8 PM UTC. @themiked added by saying that this may not be a priority for the Dev Team as there should be a docs representative for every release.

@tomjn asked if there is a document for how to contribute to docs that has all the things? @estelaris shared a link to the Docs Handbook. @mkaz also shared a link to the Block Editor Handbook. @jouisly suggested that the Handbook should be easier to discover.

@milana_cap suggested that we should make a list of the musicians in our team. She also shared her list and requested others who can play an instrument or into music to comment in this post.

#meeting-notes, #meetings

Summary for Docs Team Meeting: March 2, 2020

Attendance

  • Milana Cap
  • Jon Ang
  • Yui ゆい
  • Denis Žoljom
  • Prashant Baldha
  • Chris Van Patten
  • theMikeD
  • Jb Audras
  • Akira Tachibana
  • Estela Rueda
  • Birgit Pauli-Haack
  • Jono Alderson
  • John Blackbourn

Actionable Points

  • Jon to await Matt’s response to his questions about licensing of content on w.org.
  • JB to ask about proposing changes to recommendations in the next coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. meeting (not docs specific).
  • Jon to investigate cross-posting the announcement of the start of the meeting in #core.
  • Estela to propose further discussion of the docs reclassification for next week’s meeting.

Next Meeting

Monday, March 9, 2020, 15:00 UTC on 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/. #docs

Documentation Licenses

Jon has spoken with Shiobhan McKeown and Sam Sidler who’ve informed him that the Codex is licensed under GPLGPL GPL is an acronym for GNU Public License. It is the standard license WordPress uses for Open Source licensing https://wordpress.org/about/license/. The GPL is a ‘copyleft’ license https://www.gnu.org/licenses/copyleft.en.html. This means that derivative work can only be distributed under the same license terms. This is in distinction to permissive free software licenses, of which the BSD license and the MIT License are widely used examples. v2. Much of the content on HelpHub originated from the Codex, therefore relicensing the content would likely involve getting explicit permission from every author involved for every line of documentation.

Jon is waiting for Matt Mullenweg to confirm about the existing licensing of the Codex, there is currently no license declaration on the Codex.

It was pointed out that many handbook pages were written from scratch, but there’s a good chance that they contain derivative content from the Codex anyway. This means they may need to remain GPL licensed.

Chris van Patten pointed out that GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/’s documentation is part of the Gutenberg repo and therefore falls under its same GPL license.

The REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/. documentation is currently unlicensed.

WP-CLIWP-CLI WP-CLI is the Command Line Interface for WordPress, used to do administrative and development tasks in a programmatic way. The project page is http://wp-cli.org/ https://make.wordpress.org/cli/ documentation is MIT licensed.

Jon will follow up with further discussion on this topic in a post on the Docs 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/.

Policy for External Linking

Jon pointed out that various docs on w.org link to external resources that might not be correct and might not have been audited. Akira confirmed that dead links and some links with heavy advertising were removed during the migrationMigration Moving the code, database and media files for a website site from one server to another. Most typically done when changing hosting companies. to HelpHub.

Jon posed whether such links should be audited, removed, or left, what kind of links should get in or not, and what kind of links are appropriate, and what to do about links whose content changes over time.

A few people expressed interest in discouraging external linking at all, but there was no consensus. Further discussion needed.

Jono mentioned that the general policy of the forums is that linking out is bad, because links break, and because the motivations and value of external resources can’t be trusted, but noted that this can mean users miss out from accessing otherwise valuable external resources.

Open Floor

JB asked what is the best way to propose changes to the “abbreviation best practices” section of the Core Handbook. He’s going to mention it during the next core chat as this isn’t specific to the docs team.

Estela mentioned that she’s unsure about how to proceed with the documentation reclassification. Jon suggested bringing this up for further discussion next week, Estela agreed.

John (myself) pointed out that the starting of the #docs meeting doesn’t get automatically cross-posted into the #core channel like other meetings do. Jon will investigate.

@kpdesign has been working day and night to…

@kpdesign has been working day and night to get the 4.1 version article filled up leading up to this week’s release. She could really use some help getting it into shape.

In particular, the Under the Hood section could use a bit of work by folks who have more intimate knowledge of coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress.. These would be people like @ipstenu, @sewmyheadon, @dh-shredder, @boonebgorges and others who have helped out in the past.

If you think you know someone from the core team who could lend a hand, please please point them this way.

Some items may also need to simply be reorganized from section to section. Any and all help would be greatly appreciated.

We’re primarily working off of two checklists:

Anything checked off has already been added to the version page in some form, or skipped for brevity.

#codex, #core, #release, #sprint

Agenda for today's Inline Docs chat

It’s been awhile since we’ve had an inline docs chat, and there are several items on the agenda for today’s meeting at 19:00 UTC (3:00 pm EDT) in IRC in #wordpress-sfd:

  • 4.0 Audit – #28885
  • Access tags for all the methods
  • Hook aliases + PHPDoc tags
  • PHPDoc tags for unit tests – #28558

If you’d like to suggest any additional items for the agenda, leave them in the comments below. Thanks!

#core, #inline-docs

Documenting all the dynamic hook aliases

A couple of weeks ago at Open SourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. Bridge, I started a conversation with @jorbin about an idea to document common aliases of dynamic hooksHooks In 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. in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. docs. A long-standing pain point in core, and now in the Code Reference, is that dynamic hooks aren’t really searchable.

For example, let’s say I want to search for the ‘publish_post’ hook. If I search the source, I see add_action() calls referencing that hook, but its origin is nowhere to be found. This is because the hook is actually {$new_status}_{$post->post_type}.

The idea would be to make it possible to search the source and the Code Reference for indexed common aliases like ‘publish_post’ and have it return the reference for {$new_status}_{$post->post_type}.

Great, so what’s next?

We’ve already started a spreadsheet at the 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. Seattle 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/. to begin identifying common aliases of all of the dynamic hooks in core. Big thanks goes to @trepmal for providing a complete list of all dynamic hooks from her presentation slides.

If you’d like to get in on the ground floor and help out, the spreadsheet can be found here: https://docs.google.com/spreadsheets/d/1QfHEPhI9j_Dts5XAxC_kX-LvdE0fxyHlnRFomOTFzQk/edit#gid=0

Over the next few weeks, I’ll be working with @rarst to devise a solution for parsing hook aliases using WP-Parser. When we have a solution in place, we start planning the effort to begin patching hook docs in core.

We’ll be tracking progress on #557-meta on 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. TracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub.https://core.trac.wordpress.org/..

Yay progress!

#core, #inline-docs

Core string feedback

Would anyone care to provide some wordsmithing services over in #28199? It’s just one string change that needs docs feedback

#core, #docs-feedback

Revisions help tab

revisions_help_tab

Yesterday in DevChat, @ocean90 requested we write a help tab for the new revisionsRevisions The WordPress revisions system stores a record of each saved draft or published update. The revision system allows you to see what changes were made in each revision by dragging a slider (or using the Next/Previous buttons). The display indicates what has changed in each revision. screen. I’ve uploaded a first-run patch and am looking for feedback and revisions (ha) on that text.

I’d just like to note that I think we can be succinct about this without leaving out important information.

The ticket and patch are on the #23899 ticket.

The following is the first-run text:

Tab: Overview:

This screen is used for managing your content revisions.

Revisions are saved copies of your post or page, which are periodically created as you update your content. Text highlighted in red shows what content was removed, highlighted in green shows what content was added.

From this screen you can review, compare, and restore revisions:

  • To navigate between revisions, drag the slider arrow left or right or use the Previous or Next buttons.
  • Compare two different revisions by selecting the ‘Compare two revisions’ box to the side.
  • To restore a revision, click the Restore This Revision button.

Tab SidebarSidebar A 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.:

For more information:

Revisions Management
Support Forums

Side note: The Revisions Management page is slated for pre-sprint release, in other words, it’ll be done in time for the 3.6 release so forum folks have something to reference.

#core

What it means for a taxonomy to be hierarchical

We\’ve all done it, had to explain the difference between hierarchical and non-hierarchical taxonomies (categories and tags).

In a recent ticket, #23447, it\’s proposed that the description for the parent dropdown on the hierarchical taxonomyTaxonomy A taxonomy is a way to group things together. In WordPress, some common taxonomies are category, link, tag, or post format. https://codex.wordpress.org/Taxonomies#Default_Taxonomies. form be rewritten to be more generic. In an age of custom taxonomies, I think we can get behind that.

The current patch suggests changing this:

Categories, unlike tags, can have a hierarchy. You might have a Jazz categoryCategory The 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging., and under that have children categories for Bebop and Big Band. Totally optional.

to this:

You might have a Jazz category, and under that have children categories for Bebop and Big Band. Totally optional.

I think we can do better. We\’d need to succinctly explain \”hierarchy\” without button-holing ourselves into just talking about categories.

As @dd32 aptly points out, we need to avoid using taxonomy labels in any future changes because of the difficulty in working with different languages.

So who has a suggestion? 🙂

#core, #taxonomies