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.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
- 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 Slack channel.
Although we have a fixed schedule of weekly meetings, you can contact the Docs Team at any time through our Slack channel.
+make.wordpress.org/accessibility/
+make.wordpress.org/cli/
+make.wordpress.org/community/
+make.wordpress.org/core/
+make.wordpress.org/design/
+make.wordpress.org/hosting/
+make.wordpress.org/marketing/
There is a slippery slope to consider which I am sure was considered carefully in the decision to allow external links at all.
So it seems there must be a human element involved in deciding whether a domain is trusted. Therein, a set of standards and a team to monitor the submission of a domain for approval would be in order something like the process and guidelines in place for plugin review.
Hopefully we can have a “allowed” list that will be used in automatic filter of the content so that part should be easier for the team but populating this list and making criteria for it requires human effort.
The main focus is providing quality and useful content for users of documentation but also preventing politics, nepotism and all other misuses of this decision.
At this moment, creating fair and clear criteria is the most important thing to do. It will make or break the initiative.
+make.wordpress.org/meta/
+make.wordpress.org/mobile/
+make.wordpress.org/plugins/
Should also establish what causes a source to lose it’s “trusted source” qualification (probably not identical to what qualifies a source as trusted).
Example: @milana_cap mentioned in Slack that in order for a personal blog to qualify, the author has to be “active in community”. We need to define “active in community” to both qualify and be disqualified as a trusted source.
A challenge with the “active” requirement is that it is quite possible for a post that was the authoritative reference on a feature or quirk of WordPress to still be relevant long after its author has moved onto other things. I find I regularly end up on the blogs of former core contributors or inactive committers, and the material in most cases is still as relevant (and more comprehensive than our core docs) as it was originally.
Exactly.
My position is that there should be a significant difference between qualification and disqualification: “active” should absolutely be a qualification, and “inactive” should NOT be a disqualification.
Those are great points. My initial suggestion for “active” contributor has root in idea that someone deeply involved in the matter most likely know better than others who things work and why.
Obviously, I didn’t consider this scenario when they stop being “active” and their content is still relevant.
I guess it comes down to this:
As being “active” in community makes you a contributor but moving on to other things doesn’t nullify your contributions, I think we can apply the same logic here as well. If the content was relevant once (due to your deep involvement in the community) it is absurd to consider it irrelevant if the topic hasn’t changed.
Just a few quick thoughts/ideas:
Does the team want to open a form where everyone can suggest a trusted domain and team makes the decision, or will the list be harvested by the team members? The first option could probably cause lots of work, but grow the number of trusted sites.
If the site is someones personal, the owner should show active contribution and/or have some pre-defined wp.org profile badges to become a trusted source.
Company blogs/sites are much much harder. Even tho those contain much valuable information, would it make sense to scope those out (at least for now)? Some arguments why that should be done:
The whole idea comes from links we already have in documentation. Many of those are just copy/pasted from Codex where everyone could edit the content.
So, this is not a call for external resources, this is first and foremost creation of policy to decide what to do with those links. Some of them are very valuable and it would be a shame to lose them but we can’t start removing some and leaving the others without a clear criteria being created and applied.
I don’t think we will ever open a call for trusted sources as the sources themselves are not our interest without the context. There are many great resources but what is important is the relevance to our documentation. So the procedure will most likely be that someone knows a great article/tutorial about topic that already exists, or is in creation, at wp.org. We take a look at resource, consider all the criteria that we are trying to define right now and decide whether to add this resource to “allowed” list or not.
I agree on the point for commercial websites. We are doing our best to remove all instances where any kind of branding is appearing. These are mostly plugins recommendations found in end user documentation.
We are trying to be as “neutral” as possible. There are forums and other platforms for recommendations and discussions about different products. We are documenting only what comes with “clean” WordPress install or will become part of it (e.g. new features in Gutenberg plugin that will eventually end up in core).
A conflict-of-interest policy will make or break this 🙂
I know. This is why we are very careful with this phase of creating specifications.
Am I right in understanding that any link that is lesser known, but may very well contain very useful information about that particular subject will not be allowed?
I am active on WordPress, but one link to a specific asked-for tutorial on my add-free, cookie-less, non-tracking blog still got me under moderation for 6 months.
My opinion is that if a moderator has doubts about a given link, it should be visited first. If the information is indeed trustworthy, true and on topic, there should be no reason to have it blocked. Right?
“Lesser known” implies that we already have some kind of criteria for allowing/removing external links. We don’t. This is the very discussion for creating one.
I’m not sure what is this referring to. We have not conducted any reviews yet. Can you be more specific?
Yes, we will visit all links and consider all requirements we decide on. We still haven’t decided anything and I’m getting the impression that you have experience from another team’s reaview. Am I right?
(@theMikeD covered a lot of my points when voting for the policy.)
Questions I’m thinking about:
crstauf-1. If a blog post is written during WP 5.4.2 (latest release), and the source is (at that time) determined to be trusted, but then doesn’t write a blog post and WP 8.x is now latest, does that disqualify the source as trusted? Why (not)? Is there a difference between a “trusted source” and a “relevant” or “contemporary” source?
crstauf-2. How do we keep track of domain owners? If a “trusted source” is allowed to expire or changes domain, how do we track that, and prevent someone else from purchasing and posting unqualified but labeled “trusted” content?
crstauf-3. What content or actions are required to be disqualified? How do we monitor that at a decent level?
crstauf-4. Is there any concern with users/companies that make money from WordPress development being considered “trusted sources”? Web hosts for example: they’re likely a trusted source, but they financially benefit (possibly significantly) from being labeled as such. Perhaps a non-issue given WordPress Web Hosting document?
crstauf-5. Do we allow self-posting? If I’ve a blog post, am I permitted to leave a comment on relevant WordPress doc to my article? If there’s nothing keeping me from copy-and-pasting the article, then the only difference is my site receives increased SEO from the authority level of WordPress docs; is that permissible?
crstauf-6. Is there a difference between “trusted” and “quality”? For example, once a user is considered trusted, what prevents them from writing an article for every article in WordPress docs, and posting a link to their own article? Is there a quality requirement for an article to be accepted?
crstauf-3. A reader of some kind with team access and subscriptions to all trusted sources to read their latest content is a decent option, but does require more effort from existing team members, or more team members.
I know for me it would be valuable: a centralized location of posts from trusted sources would be a treasure trove for developers. Maybe it could even be public, as an added benefit to trusted sources?
Yes, I am thinking about having the list of all linked articles from each trusted resource. Once we want to add another one we can check the rest and see if they’re still valid.
That could be a public document with read access.
crstauf-1. My position is that there should be a significant difference between qualification and disqualification: “active” should absolutely be a qualification, and “inactive” should NOT be a disqualification.
(First posted here in reply to @kadamwhite.)
crstauf-4. I vote no. As a WordPress developer, being considered a “trusted source” would also benefit me financially, and probably encourage me to contribute more, to continue to receive more inbound links from WordPress docs.
The practice so far has been removing all branding from documentation. We are not recommending any plugins/themes, nor we are documenting the usage for anything other than fresh WordPress install.
Personally, I’d like to keep it that way. All commercial websites for hostings, plugins etc, have some kind of marketing content in their blogs. Regardless of post being “general” or “wide applicable”, there’s always a piece saying how to apply that on their product. And that’s perfectly fine for their blogs.
But for WordPress documentation I believe it’s important to prevent any kind of favoring branding and avoid any situation that might make any member of this community question the interests behind any part of documentation.
If an active, or formerly active, member of community publish about their niche on their personal blog and that content is expanding our documentation and could be valuable for users of our documentation, I’d say this member’s blog deserves to be labeled as “trusted” resource.
Somehow I missed that one and replied here.
I will also address all the other comments here by the end of the week.
We can get help from Marketing team and run link checker for broken links. We can also have a list of linked material from each “trusted” resource. Once someone add another link to the list, we can check the rest of them to make sure the content is unchanged and relevant.
We still don’t have the workflow sorted. All suggestions are welcome for that phase of the initiative. However, for now we are focusing on requirements for being “trusted” resource.
I already replied on this question here.
In short, the workflow shouldn’t allow one-man decision. Every new resource first has to be proposed and then reviewed. The decision will be explained and published so the reasons and names are available to everyone. With such workflow there should never be a conflict of interest but I’m ready to be surprised.
Yes, there is. Once labeled as “trusted” doesn’t mean we won’t review any other content coming from it. It only means we trust that already published links won’t be changed. Every new link will be reviewed because the focus is on content being relevant. Having “automatic” filter on allowed domains doesn’t mean anyone can add external links anywhere and no one checks that. This is why we have people responsible for different projects in documentation. It is their job to keep an eye on every contribution to the project and make sure nothing unwanted happens. Having control over content is one of benefits in moving from Codex to WordPress.
Now, if someone wants to dedicate their blog to content that is expanding WordPress.org documentation, so be it. It still has to be reviewed before adding the link, every single post.
There are a significant number of resources in the documentation (probably migrated from codex) that provide real value to certain articles. A majority of the high value items are likely to not be on the `trusted domain` list due to them being on personal blogs.
I would hate to loose access to those resources (many of which taught me an awful lot of what I know in years past).
I vote no to them being automatically removed. They could be automattically ‘hidden’ and verified by community members. I understand that such a task is a hige burden on the team and as such I will be willing to spend time myself helping with that task.
A blog being personal doesn’t disqualify resource from being trusted. On the contrary, those will be prefered and general idea is to keep documentation branding and commercial free.
We still don’t know what will the workflow look like but I can assure you that no link will be “automatically” removed. We’ll start creating the “allowed” list from what we already have.
Thank you for volunteering to help, I’ll keep that in mind 🙂
Will this include what I post on make.wordpress.org/community ?
Currently, I’m doing workshop signups at:
That is my list at present, but that list could change at any time, as we evolve or unexpected needs show up. Sometimes this needs to be a last-minute change meeting a short deadline. I’m nervous about how having this restriction is going to affect the important community diversity work that my team is doing.
As for other links, it’s tough for our work as we occasionally want to point to a link with relevant diversity info outside of WordPress, or show a link where our Diverse Speaker Training group’s (#WPDiversity) work has been featured, and we wouldn’t know the list in advance as that comes up from time to time in different places…
If this also includes the handbooks, the diversity documents display links to valuable external resources that are important to include.
(See example: http://wayback.fauppsala.se:80/wayback/20200829174748/https://make.wordpress.org/community/handbook/wordcamp-organizer/first-steps/inclusive-and-welcoming-events/ )
Happy to be corrected here, but I think this issue is specifically centered on what is linked to from the Codex and from HelpHub. Is that right, Milana?
Yes, links on DevHub and HelpHub pages.
Yes, that is correct. This will effect only end user and developer documentation. Not contributing documentation (make team Handbooks).
Thank you @bph for prompt response <3
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?