WordPress Documentation Team Bans Links to Commercial Websites

This week WordPress’ Documentation team announced a ban on links to commercial websites in a revision to its external linking policy:

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 plugin’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.

Despite the announcement’s abrasive phrasing discouraging further discussion on the matter, the controversial decision stirred up a heated conversation in the comments. Yoast founder Joost de Valk contends that companies contributing to WordPress might as well receive some promotion as a benefit:

I understand that you want to prevent discussions about bias.

But I think your premise here is wrong: you’re saying you’re not “biased” if you’re not linking to commercial companies. I would say we’re all inherently biased, because some of those companies do a lot for the WordPress community, while others do not.

The companies that contribute to WordPress a lot used to get some links, and thus some promotion as benefit from the fact that they’re contributing. By removing that from them, you’re basically treating those that don’t give back the same as companies that do give back, something which I think is simply wrong. So I very heavily disagree with this decision.

Milana Cap, the Documentation Team member who penned the announcement, clarified that the policy change does not remove external links to commercial sites from WordPress.org. It only applies to documentation sites, including HelpHubCode ReferencePlugin and Theme Developer Handbook, Block Editor HandbookCommon APIs Handbook.

“There is no way to make this fair,” Cap said. “And we can discuss about many unfair parallels happening in open source communities; such as how many hours per week can be contributed by a freelancer vs paid company contributor, meeting times (where decisions are made) in the middle of the night in your timezone etc.”

Timi Wahalahti suggested one solution would be to better utilize the Five for the Future pledges page to identify significant contributors to documentation if links to commercial sites are no longer an option.

Several commenters noted the value of linking to additional examples and resources but also recommended WordPress put a version or timestamp in place to give the reader more context.

WordPress agency owner Jon Brown characterized the ban as “undesirable gatekeeping,” saying that the policy suggests all things commercial are “inherently corrupt and not trustworthy nor valuable.”

“A links value is inherently subjective and ought to be delt with subjectively,” Brown said. “Trying to create high level objective rules doesn’t seem beneficial or realistic. I certainly disagree that all ‘commercial’ sites should be blanket banned.

“I do think there are some low level disqualifiers that could guide authors and moderators in what links are appropriate. Those should be criteria that directly impact the users of docs, and being commercial doesn’t. Those are things like, the source being accessible, the source not being pay walled, etc.”

Cap responded, saying that the root of the issue is that allowing commercial links puts the documentation team in the unwanted position of having to find a fair way to decide on which links are allowed to be included. She also indicated that the policy may evolve over time but that for now the decision on the ban is final.

“Perhaps over time we’ll figure that out,” Cap said. “We’ll certainly know more once we start doing it. For now, this is the decision.”

External sources can be valuable supplements to documentation, but this conversation underscores the need for better incentives for people to spend time documenting WordPress. As the team is already running on limited resources, they are trying to avoid having to heavily police links to commercial websites.

“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,” Cap said. “We do expect to eventually get towards discussing how we can safely include commercial blog links (if this even is possible).”


12 responses to “WordPress Documentation Team Bans Links to Commercial Websites”

  1. Documentation is marketing, first of all. Secondly, if the Marketing Team had front-facing publishing ability maybe there would be content on WordPress.org. The Make WordPress ecosystem is handicapped from publishing good, useful content. I have personally had this issue when I was the Marketing Team Lead and we produced content per the Growth Council’s direction only to be turned away by Meta Trac.

    If Make WordPress can’t write the content, why not link out until the content is written?

  2. Blanket policy making at its finest. I agree with Joost and Jon. This is a bad decision. I’m sure this policy won’t succeed and will undoubtedly fail. There’s too many excellent resources from commercial companies. Wow, just wow.

  3. Great decision, documentation is not marketing and linking to commercial sites is breaching the idea of having non-profit incentivized documentation.

    I am tired of seeing companies manifesting their close relationship with WP and profiting out of that. Looking at some popular “SEO” plugins.

      • What do you mean by “distributed”, Marc? Do you think that this change will significantly push companies away from WordPress? To an outsider like me, these comments from those representing companies just seem like whining. I can’t imagine this change will have any significant impact; I’ve never seen a link to third-party sites in all my time browsing Codex or Developer Resources.

  4. Relevance is the key. Just like a Google algorithm, links should be judged on their direct relevance to the content, regardless of whether or not the endpoint is commercial or not. This is the only policy that places the USER as the priority. Which surely must be the point of having the documentation in the first place?

  5. In the past, the Codex linked to several of my tutorials (not sure if those links are in the more recent docs). And, those tutorials were on sites with commercial purposes. My goal with those tutorials was purely to pass on knowledge that I learned — of course, I benefited indirectly from links to those pages. There are many such tutorials and other forms of documentation on other sites. Even if writing docs is not entirely altruistic, they still hold value as a free resource.

    I’d hate to see users and other developers miss out on valuable information over such a policy decision. It sounds like this is a preemptive decision to stop possible abuse rather than abuse that is actively taking place.

    • The issue is that some of the WordPress ecosphere commercial companies abuse linking opportunities and create shallow, farmed, non-expert and commercial content on their weblogs in order to link farm. Some of those companies are those complaining loudest about this now.

      Your website and your weblog was never like that Justin. Your posts were often a deep read and often with no direct commercial benefit to you or your businesses.

  6. Hello, I’d like to note that discussion about external links in WordPress documentation lasts for a few months now and is NOT finished. We still haven’t made any final decisions. It’s rather difficult discussion where we are trying to create an policy that will serve us all.

    For more info and joining the discussion please follow external-linking-policy tag on Docs team blog. Thank you.



Subscribe Via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

%d bloggers like this: