Last month the WordPress Documentation Team announced a ban on links to commercial websites within the official docs. These include the HelpHub, Code Reference, Plugin and Theme Developer Handbooks, Block Editor Handbook, and the Common APIs Handbook. The reason behind the ban was that heavily policing commercial links placed too much responsibility on the documentation team, when they are already working with limited time and resources.
The decision was instantly controversial, igniting a heated discussion in the comments. A blanket ban on links to commercial sites, without a clear outline of what that includes, was confusing.
“There isn’t clarity what will/won’t be allowed, you state that the rules are expected to change in the future (more lax after some trial and error), and end users lose in the end as a result of excluding actually helpful information because it’s free but at a domain that has non-free content,” Core contributor Clifford Paulick commented on the ban announcement.
The level of opposition seemed to indicate that there may not have been enough discussion up front and that other branches of the WordPress contributor community, including commercial entities who are also contributors, were not considered.
“Discussion on [the] external linking policy is going in the way we wanted to avoid,” Milana Cap said during the July 13th docs team meeting. “I was thinking to explore a different approach.” She gave more background on why the team is reconsidering the ban:
The reason we didn’t want to allow ‘commercial’ links is to avoid abuse and make it ‘fair’ for everyone and not promote any product. We also wanted to save time for our members in a matter of maintenance and sort of automate the process. The further and deeper discussion goes I’m realizing this will not be possible. It won’t be fair, we won’t save time because we’ll have to do through discussion every time someone suggest ‘commercial’ link and I’m pretty sure we’ll never come to agreement on what’s ‘commercial.’ Personal blogs, services, products.. all of it is mixed now. So my suggestion is to allow them all, make process transparent and set strict rules about the actual ‘content.’
A Google document is now home to a collaborative effort on a new policy that Cap says is “fundamentally different from previous discussions.” The new approach proposes a set of criteria for allowing external links, banning things such as product promotion within the tutorial, affiliate links, paywalls, and tracking. The specific criteria and wording of the new policy are still under active discussion.
Sometimes it pays to speak up, if you have a strong opinion about a decision. Reconsideration of this external linking policy is the direct result of feedback on the initial controversial decision, even after it seemed to be final. This may result in a better solution for all stakeholders involved in this discussion.
Next week the Documentation Team will be hosting a Zoom call to discuss the proposal they have been collaborating on in Google docs. This meeting is for anyone who is interested, not just Documentation team members. If you want to get in on the discussion, check out the Doodle poll for the proposed dates and times.
