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 “beta 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:
- Classify all external links found in the Handbook;
- Define “undoubtedly allowed” links;
- Propose a list of “undoubtedly allowed” links;
- Define “pre-allowed” links;
- Propose a list of possibly “pre-allowed” authors and websites;
- Propose phases of the acceptance process and draft their definitions;
- Start discussion about pre-allowed list and acceptance process phases;
- Draft a timeline of actions for next steps;
- Select at least 3 Docs team members who will act as “official reviewers” for this first review.
All external links found in the Plugin 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 GitHub 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:
- Define and apply “undoubtedly allowed” links. Document the process along the way.
- Define and apply “pre-allowed” personal and non-personal resources. Document the process along the way.
- 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:
- “Undoubtedly allowed” phase finished by the end of 2020.
- “Pre-allowed” phase finished by the end of February 2021.
- “The rest” phase finished by the end of May 2021.
If we completed everything within this timeline, WordCamp 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 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
– docs team update was given by 
