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 releaseRelease A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software.. 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 releaseRelease A release is the distribution of the final version of an application. A software release may be either public or private and generally constitutes the initial or new generation of a new or upgraded application. A release is preceded by the distribution of alpha and then beta versions of the software., 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