External Linking Policy – 1st review of Plugin Developer Handbook

As the title suggests, this is a first review, using the Plugin Handbook as the testing documentation. We will conduct this initial process to work out the External Linking Policy, which is currently still in “betaBeta A pre-release of software that is given out to a large group of users to trial under real conditions. Beta versions have gone through alpha testing in-house and are generally fairly close in look, feel and function to the final product; however, design changes often occur as part of the process.” phase. Over time, the policy will evolve and take shape as we better understand what it should cover.

The Goal

The goal of this first review has several points:

  1. Classify all external links found in the Handbook;
  2. Define “undoubtedly allowed” links;
    • Propose a list of “undoubtedly allowed” links;
  3. Define “pre-allowed” links;
    • Propose a list of possibly “pre-allowed” authors and websites;
  4. Propose phases of the acceptance process and draft their definitions;
  5. Start discussion about pre-allowed list and acceptance process phases;
  6. Draft a timeline of actions for next steps;
  7. Select at least 3 Docs team members who will act as “official reviewers” for this first review.

All external links found 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 can be found in Docs team’s Google Drive document (with occasional comments from the first review performed by myself): https://docs.google.com/spreadsheets/d/1GhFv8p9veimVM3jMhhazttJLunRjcW7pg0-WO5E0NRk/edit?usp=sharing

1. Classify all external links found in the Handbook

While performing my first review, I classified all resources into “Personal authors” and “Non-personal domains”. This is a very rough classification based on one single difference. 

A person can publish content on different websites and therefore can come out as authors on different resources of which some may meet our policy and some may not (e.g. promo article for a plugin/theme/service). On the other hand, if said person’s content, published 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/, gets accepted, it doesn’t mean we will accept all resources hosted at github.com.

Non-personal domains with a single author represent one set of rules/values/niche etc and therefore come out as a singular resource that won’t publish content at different domains. Non-personal domains with multiple authors, such as GitHub, YouTube, npmjs etc, can not be seen in this case as a single resource but rather as a tool where different persons publish their content. Seeing GitHub as a singular resource would make sense only if we would consider for example their official blog.

2. Define “undoubtedly allowed” links

What does “undoubtedly allowed” mean?

“Undoubtedly allowed” refers to official or authoritative resources for their respective topics. They go in depth with their topics, and we can expect them to be the most up-to-date resource on that topic. Examples include php.net, gnu.org

2a Define links that can stay and be “undoubtedly allowed”.

Out of all links found in Plugins Handbook, this is my proposed list for “undoubtedly allowed” domains: 

Please note that this list is made up of links actually found in the Plugins Handbook; we don’t need suggestions for random sites not currently in the docs. Please feel free to post your own list in the comments below, once you make sure that your proposed addition actually exists in the Plugin Handbook (provide a link please).

3. What does “pre-allowed” mean?

“Pre-allowed” means that we know this person or website has been giving sound advice and has been nurturing WordPress’s values and principles in the past. Therefore, we have a reason to believe this practice will continue in the future. It does NOT mean that this content will be exempt from review for its relevance and up to date information. 

Links in this classification will not go through the whole “acceptance process,” but rather a content check: 

  • Is it relevant for the part of documentation where it is proposed?
  • Is the information up to date?
  • Is the content in whole meeting External Linking Policy requirements (e.g. not recommending specific plugins/themes/services)?

3a. Propose a list of possibly pre-allowed authors and websites.

Please go through the list in this document and post your “pre-allowed” proposal in comments below. If you feel you should explain your choice, please do. 

This will help us understand values and holes people see in WordPress Documentation and will be a huge starting advantage once we move into the next phases of this policy.

4. Propose phases of the acceptance process and draft their definitions.

In the aforementioned document I have created a “Status (Acceptance phase)” column to indicate the phase in which each link is currently classified. The list of phases will directly affect the whole review workflow so it is reasonable to expect this to change and the workflow to be refined in the future.

Some phases we can be sure to keep all the way, obviously. Such as:

  • Reviewing
  • Accepted
  • Rejected

However, “Reviewing” is rather broad and vague. This phase could be expanded further to, perhaps:

  • Reviewing – Relevance
  • Reviewing – Updated info
  • Reviewing – Advertisement
  • Reviewing – Free access (no paywalls etc)
  • Reviewing – Website/webpage (upholding WordPress values etc)

Broken into smaller phases, the Review phase can be performed easier while the whole process gains clarity and transparency.

If you have any suggestions for phases of the acceptance process, please post them in comments below.

5. Start discussion about pre-allowed list and acceptance process phases.

Hopefully, the comments section will be sufficient for a constructive and productive discussion. If not, we can organise another conference call meeting and clarify all that is indistinct and vague. 

6. Draft a timeline of actions for next steps.

The ultimate goal for Plugin Handbook, as the guinea pig for this process, is to clean up all existing external links, remove invalid ones and (if necessary) restore any valid ones (both, personal and non-personal). 

During this process, we hope to define a pretty solid policy that works in the best interest of Documentation consumers.

To draft a timeline of actions for documentation where we already have external links, first we need the actions defined. While working on this initiative and thinking about possible scenarios, personally I can identify few steps:

  1. Define and apply “undoubtedly allowed” links. Document the process along the way.
  2. Define and apply “pre-allowed” personal and non-personal resources. Document the process along the way.
  3. Review the rest of the links, remove unfitted and keep fitted ones. Document the process along the way.

It’s hard to estimate a process that we have never done before (even the ones we have) but we do need some time frame to make sure this project doesn’t end up unfinished. 

By rough estimation, I’d say that this process could last 6 months in total. First step should be the shortest: ~ 1 month, the last one looks like the longest so I’d give it 3 months which leaves us with 2 months for the second one. As we have already stepped into the first one, the timeline could then look like this:

  1. “Undoubtedly allowed” phase finished by the end of 2020.
  2. “Pre-allowed” phase finished by the end of February 2021.
  3. “The rest” phase finished by the end of May 2021.

If we completed everything within this timeline, 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. Europe 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/. could be a good moment to start work on other parts of Documentation.

7. Select at least 3 Docs team members who will act as “official reviewers” for this first review.

These 3 Docs team members will be noted as a committee who approved “undoubtedly allowed” links. Of course, the more people conduct review and share feedback – the better, but we need defined names responsible for allowing/rejecting resources to make sure reviews will be conducted in full and taken seriously.

Obviously, I already did the first review, so I need two more volunteers who are members of the team and familiar with this whole initiative.

If you are interested, please post it in the comments below.

#external-linking-policy

External Linking Policy – Meeting Notes August 25th

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

External Linking Policy – Zoom Meeting Agenda

In previous post about External Linking Policy we invited everyone to participate in Doodle for selecting the time and date for conference call via Zoom. The selected meeting time is tomorrow:

Tuesday, August 25, 2020, 19:00 UTC

Zoom link: https://us02web.zoom.us/j/84003455984?pwd=ZzJnY3hVRU9SYy9mNWpRUk40WEJIdz09

Topic: WordPress Documentation Team - External Linking Policy

Join Zoom Meeting
https://us02web.zoom.us/j/84003455984?pwd=ZzJnY3hVRU9SYy9mNWpRUk40WEJIdz09

Meeting ID: 840 0345 5984
Passcode: 921806
One tap mobile
+16699006833,,84003455984#,,,,,,0#,,921806# US (San Jose)
+19292056099,,84003455984#,,,,,,0#,,921806# US (New York)

Dial by your location
        +1 669 900 6833 US (San Jose)
        +1 929 205 6099 US (New York)
        +1 253 215 8782 US (Tacoma)
        +1 301 715 8592 US (Germantown)
        +1 312 626 6799 US (Chicago)
        +1 346 248 7799 US (Houston)
Meeting ID: 840 0345 5984
Passcode: 921806
Find your local number: https://us02web.zoom.us/u/kbyR5ZUocj

Everyone is invited, even if you didn’t participate in selecting the time. If you can attend, you’re very much welcome to do so.

We are planning to continue discussion started in this document, so please get familiar with it if you are planning to join.

Agenda

  • Brief introduction with goals of this policy.
  • License – This seems like the topic that needs the most clarification.
  • Contributors support – How do we make sure to include support to community contributors, people and companies?
  • Promotion, affiliates, paywals, tracking – Appears we do agree on majority of these items.
  • Open floor.

If you have any suggestions for Agenda items, please add them in comments below.

We are planning to record this meeting for everyone who are unable to attend. Using camera is not required.

Thank you everyone for participating and looking forward to see you in Zoom.

#external-linking-policy

External Linking Policy – Doodle for New Approach Discussion via Zoom

Past few weeks Documentation team has been discussing a new approach to External Linking Policy that has been drafted in this document. It is fundamentally different from previous discussions.

We still have some items to clear out and come to agreement about and we believe that conference video discussion would help us better understand each other and move forward. In order to get as many people as possible attend and join this discussion we set up a Doodle with time slots spreading over next week.

You can vote for time slots that fit in your schedule next week and, hopefully, you’ll join us. We want to hear your opinions on the subject.

This is a call for everyone, not just Documentation team members.

In order to keep discussion constructive and to honor the volunteered time of every participant, please make yourself familiar with forementioned draft. You can, also, leave comments on it.

The Doodle for picking the right date and time is here: https://doodle.com/poll/v8yy7auidw3mm6q2

Looking forward to see you there. Thank you.

#external-linking-policy

External Linking Policy – “Commercial blogs”

During discussion about external linking policy, we came to conclusion that we won’t allow, at least in the beginning and for the time being, any commercial blogs. So before you start arguing that some popular 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’s blogs have valuable information, let me stop you right there.

Allowing “popular plugin’s/theme’s/services’ etc blogs” and all other commercial blogs will put us in a position to protect documentation from being abused as marketing media, to protect ourselves from accusations of being biased and to defend every decision we make along the way. And still, there will be dissatisfied sides claiming we weren’t fair and did them wrong. The idea of allowing external linking will become its own purpose.

Additionally, this will completely move focus from initial idea which is:

Benefit for the documentation user.

If this process should cost Documentation Team too much of a time for weighing, deciding and defending made decisions, then there’s no time for actual contributing and there’s no benefit for anyone.

So any WordPress plugin official blog, theme’s official blog, market’s or shop’s (with themes, plugins etc) official blog, hosting’s official blog, other service’s official blog etc regardless if they are selling anything or not, is not allowed. This is why word commercial is wrapped into quotation marks.

This is in accordance with HelpHub’s (end user documentation) practice that no plugin, theme, hosting etc will not be promoted or recommended. In HelpHub we are documenting only what’s in coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. or will be in core.

The same applies here. If the website is dedicated to a specific WordPress product (free or not), it is not allowed. These sites usually have the product name in domain name but we are not going to limit the criteria there. I’m sure some cases will be unique and decision will have to be made specifically for it.

The bottom line is: we haven’t figured out the best way to  deal with commercial blogs or sites in a fair manner and thus our focus is going to be on links that don’t drop into that grey zone. We do expect to eventually get towards discussing how we can safely include commercial blog links (if this even is possible).

Now that that’s clear

We need to determine what is not “commercial” website but doesn’t go under personal blog either, which can be allowed. For example, Stack Overflow or any of the Stack Exchange websites. This is not really non-commercial website but its completely neutral towards appearing 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/. This is not to say that being “neutral” in this regard is a requirement but merely pointing out that they have no interest in trying to abuse the opportunity for getting their link appear at wp.org.

Some tutorial websites also comes to mind but it seems we are stepping into a gray area here. Perhaps allowing websites with only free tutorials? Are those even exist?

Let us hear your opinions in comments. All examples, ideas, questions etc are welcomed.

If you have an opinion on the subject now is the time to share it. This is important initiative and we want to make the best possible decision that will benefit the users of the documentation. Thank you. For whole discussion follow #external-linking-policy tag.

#external-linking-policy

External Linking Policy – Trusted Sources

We have been discussing policy for external links in 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/ documentation for a while now. It has been decided that, considering the benefits for the users of the documentation, we should allow linking to trusted sources when these sources are explaining the matter in more detail and/or with high quality use case examples.

In order to avoid all possible misuses of the “trusted source” label, we need to clearly define what kind of sources can be considered as trusted. Of course, it is not possible to keep an eye on each linked source all the time and we don’t want to make this at cost of our members workload. This is why the accent is on trusted.

Ideally, we will have a list of domain names which would be automatically allowed on wordpress.org. All the other domains will be automatically removed. That should sort out the workload of Documentation team members.

Also, Documentation team can and will change the criteria if a need for such an action arises. Documentation team owes to no individual or company to list them as “trusted source”. This is initiative to help people who are using the documentation in their quest for the information and guidance.

Let the discussion start. If you have an idea what would be appropriate requirement for “trusted source” label, please let us know in comments below. Thank you.

#external-linking-policy

External Linking in Docs Policy

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/ has a large number of external links mostly added to Codex and then copied to all other/new parts of docs. We have to decide on policy for external linking. Do we allow it and, if so, what is the criteria?

Even though external linking, as an idea, should be used for more in-depth explanation of the subject, things to consider:

  • External links need to be reviewed by our team members which is more work but more importantly, could cause our members unwanted situations when link is rejected
  • External links tend to be outdated (sooner than we expect)
  • We have no control if content on external link gets changed after approval, regular checking is highly undesirable another task for docs team
  • External links have been (and will be) used for gaining traffic and/or marketing own services
  • There’s probably more

We have to decide “yes” or “no” for external linking. Let’s keep in mind that documentation should be self sustained; our team members are not responsible for the content outside of WordPress.org but are responsible for the content inside of it.

Please leave your thoughts, as well as pros and cons in comments. Thank you.

#external-linking-policy