External Linking Policy – Meeting Notes August 25th

Welcome to the official home of the WordPress documentation team.

This team is responsible for coordinating all documentation initiatives around WordPress, including the Codex (moving to HelpHub and DevHub), handbooks, parts of 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/, admin help, inline docs, and other general wordsmithing across the WordPress project.

Want to get involved?

There are many ways in which you can help the Docs team. Every small contribution counts and helps! You can report an issue or typo you found in the docs, or even help us write new documentation for parts that are still missing. These are some helpful links to find out more about what we do and how to collaborate:

Docs Team Handbook: An overview of what we do and how to collaborate
Block Editor Handbook: An overview of documentation contributions of 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 / 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/
developer.wordpress.org: The home of the developers’ documentation
wordpress.org/support: The home for all end-user documentation

Weekly Meetings

Join our discussions of documentation issues here on the blog and on Slack.

The documentation team holds weekly office hours on Mondays from 15:00-16:00 UTC in the #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.

Although we have a fixed schedule of weekly meetings, you can contact the Docs Team at any time through our Slack channel.

Attendance: @kenshino, @joostdevalk, @mkaz, @cbringmann, @andreamiddleton, @justinahinon, @wpza, @themiked, @milana_cap, @chaion07

Unfortunately, Zoom recording doesn’t display participants’ names, so it can be difficult to recognise people who had cameras turned off. If you attended the meeting and your name is not on the list, please let me know, and I’ll add it.

Agenda: https://make.wordpress.org/docs/2020/08/24/external-linking-policy-zoom-meeting-agenda/

Video recording of the meeting: https://drive.google.com/file/d/1KnB9PQHZDGBGc6Zn2f7FCZsLMnIsTmGu/view?usp=sharing

Summary

In short, we’re allowing external links. We discussed that by virtue of an entity being a commercial one doesn’t make it undesirable. We’re proposing to start this slowly and the policy will mature as things move along. We’ll make a separate post on 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 define the policy a little further and leave it for a period of time for feedback.

Brief introduction and goals of the policy

As you know, official documentation has moved from Codex to WordPress. The whole content is updated, including screenshots and facts. We are required to take care of external links.

We should keep in mind that Documentation will soon have its official license. We agreed to have 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+ but there is a high chance that we will consider making this multi license and add one that is more appropriate for documentation.

Throughout the official documentation 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/, we have taken care not to directly recommend any plugins, themes, products or services. We have so far been only documenting what is inside the WordPress software, that comes in a zip file you download from the official WordPress website.

We want to make sure the external content we are linking to is expanding the content in the documentation. That content should also be free for consumption, meaning it is not behind any paywall or other additional action required from the user.

We want to ensure our user’s privacy is intact, meaning we don’t want any tracking links.

License

Policy considered: External resources should publish content under a license compatible with GPL v2+, and this should be visible on their website.

Conclusion: This is beyond our control and sets hard limits on the number of resources that meet these criteria. There is likely to be a hard line for sites that promote non-GPL derivatives of WordPress which is consistent throughout the project. Rather than insisting on the presence of a GPL compatible license, we should focus on content that is NOT breaking or advocating against GPL.

Promotion, affiliates, paywalls, tracking

Policy considered: External resources will not promote any 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, theme, product, or service on the page we’re linking to. No affiliate links allowed in content, and the content as a whole is free for consumption without requirements from the user to pay, subscribe, or share on social media.

Conclusion: This remains as is. The scope of promotions and affiliate links expands to the whole page instead of just the content, while tracking links are limited to the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL www.wordpress.org itself. The URL that we place inside WordPress.org documentation can not contain any tracking or referral codes.

Direction

“Whatever we discuss here should apply to other parts of WordPress.org too.” – @kenshino

We should be focusing on the spirit of openness. Focus on what we want, rather than what we don’t want. Describe what is desired from external resources to have, and if possible, show examples.

“These are the cases where we see the value or a need for external linking and anything we link to should meet these expectations…. Websites should uphold the values and principles of WordPress.” – @andreamiddleton

Next steps

Slowly building “allowed list”

Advice by @andreamiddleton on moving forward:

Start with a Plugin Developer Handbook, as there are leftovers from Codex.
Identify five to ten safe resources without profit motives and supported by stable organizations, which we are confident will not break (cease to exist, turn into link farms etc), e.g. MDN and ReactReact React is a JavaScript library that makes it easy to reason about, construct, and maintain stateless and stateful user interfaces. https://reactjs.org/. docs.
Define the time period in which a new group of resources will be reviewed and vetted, and create a way for people to suggest new ones. Meanwhile, consolidate the proposed links.
The documentation team should be public in its decision on which links are allowed. In the case that a disagreement cannot be resolved amicably by the documentation team, it should be escalated to the Executive Director or the Project Lead. (This was discussed and added post call)

Community members

Besides these safe resources, we can also define what makes a single person’s content trustworthy following the criteria:

A historically proven positive contributor.
Gives sound advice.
Nurtures WordPress’s values and principles in contributions and the community.

Whenever this personal content appears to fit well in current WordPress documentation, it is advised that the Documentation team try to import it, whether by asking the author to contribute it to the official documentation or asking the author’s permission for the team to do that by themselves.

#external-linking-policy