WordPress.org

Making WordPress.org

Opened 9 months ago

Closed 8 months ago

#3972 closed enhancement (invalid)

Lack of clarity re: various documentation portals

Reported by: littlebizzy Owned by:
Milestone: Priority: normal
Component: Codex Keywords: close
Cc:

Description

Firstly thanks to all the volunteers who donate their time to improving official WordPress documentation, instead of merely posting tips on private blogs to drive traffic, etc.

Since this affects all areas of the WordPress.org domain and beyond, a Trac ticket seemed appropriate.

Browsing thru the last few years of Make/Docs, users encounter several terms:

  • Codex
  • Developer Resources
  • Function Reference a.k.a. Code Reference
  • HelpHub
  • DevHub
  • Inline Docs
  • Gutenberg Handbook
  • Support Articles
  • Support Forum
  • etc

After reading thru the past few years of posts, along with Codex and Developer subdomains, it is impossible to determine which "portal" is authoritative.

The Codex subdomain further confuses things with a callout:

"Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!"

Should developers no longer be contributing to the Codex subdomain (Wiki)?

If so, perhaps the current callout should be better worded. Or, perhaps editing should be turned off in the Codex altogether at this point. Ultimately, all the terminology and messaging lacks clarity and direction.

Perhaps a more detailed callout? E.g.

We are in the process of merging the Codex portal into our new Dev portal. Any contributions you make here will be safely copied into the new portal in the near future. If you would like to post a question about WordPress, please visit our Support Forum to receive additional help from our community. Developers who are interested in following our documentation efforts may also connect with our Make/Docs team as well.

P.S. for the record, Codex ranks extremely well on Google already... is the content simply going to be copied over to the Developer subdomain instead, and edited solely by Admins (no more public contributions)? If so, that's kinda sad, and will result in a big loss in contributions, not to mention constantly outdated content...

In any regard, if the final unified portal (hopefully there is only one) is going to be called "DevHub" than a subdomain like "dev.wordpress.org" might make more sense (and better URLs/SEO)...

Change History (11)

#1 @joyously
9 months ago

This is being worked on, as a matter of fact, the HelpHub articles that have been copied from codex went live yesterday. Phase two of HelpHub work is starting, which is not fully defined.
There is a distinction between developer and user documentation. Then there is reference material, which comes straight from the code.

As for authoritative, the code is. But code can have bugs and typos.
Everything that is not code is explanation, which sometimes doesn't get changed when the code does.

#2 @DrewAPicture
9 months ago

Hi @littlebizzy, good feedback.

Let me address some of your points inline.

After reading thru the past few years of posts, along with Codex and Developer subdomains, it is impossible to determine which "portal" is authoritative.

That's a fair assessment, though actually I think a bit of an understatement.

At the moment, WordPress documentation is in the middle of a period of long-awaited evolution. In the span of five or so years, It's gone from a very centralized, albeit unmaintainable, state to a largely fragmented one, as you've alluded.

History

It's important to understand the history of why this evolution came about to fully embrace why the current state of fragmentation is actually a good thing. @joyously mentioned something that really gets at the heart of the problem, which is that for 10 or more years, WordPress entirely relied on the Codex for all of its documentation needs.

Contributor documentation (outside of the support and core teams) was largely nonexistent. User docs lived alongside developer docs, and anyone with a .org username could edit anything anytime. While the Codex was in-effect the canonical source for documentation, it was never particularly authoritative. The Codex was (and continues to be) chronically outdated, often incorrect, and in many cases, incomplete.

Fragmentation

Fragmenting both the effort and the content out to separate channels was the first and most important priority. See, on a team such as docs – where participation wildly ebbs and flows – there is a persistent need for additional help. Everybody wants and needs documentation, but very few participate in its creation. This is just a reality.

In splitting up the authorship and ownership of team documentation to the respective individual contributor teams, this largely freed up the docs teams' still-limited resources to focus on creating authoritative documentation for both developers and users, in separate respective buckets.

Official Docs

Enter DevHub and HelpHub.

The plan the docs team has been working toward for five years is very near completion. DevHub is up, and the Code Reference with it. DevHub is not user-editable, but it is interactive. It considered the official, authoritative source of developer documentation.

Phase I of HelpHub is now up on /support as of yesterday. It is considered the official, authoritative source of user documentation.

The Codex is being deprecated, piece by piece, article by article in a massive migration effort. Ultimately the Codex will cease to exist with DevHub, HelpHub, and a host of contributor team handbooks in its place.

Should developers no longer be contributing to the Codex subdomain (Wiki)?

No.

If so, perhaps the current callout should be better worded.

We could definitely do better in this regard.

Or, perhaps editing should be turned off in the Codex altogether at this point.

Unfortunately we can't really do that yet. There still exists some utility in the Codex, particularly in the realm of translated documentation. Also, we're still in the process of migrating useful information out of legacy articles. We're redirecting each migrated article as we go, but there's a lot of articles to get through and check.

P.S. for the record, Codex ranks extremely well on Google already... is the content simply going to be copied over to the Developer subdomain instead, and edited solely by Admins (no more public contributions)? If so, that's kinda sad, and will result in a big loss in contributions, not to mention constantly outdated content...

That's a bit of a loaded group of statements, let me try break it down.

  • As I mentioned, the useful and correct content is being migrated and the pages permanently redirected to DevHub and HelpHub. Google indexing picks up on the redirects and reindexes the Code Reference and HelpHub articles just fine in this regard.
  • Yes, by virtue of becoming authoritative, the documentation is now largely uneditable (at least directly) by anyone outside the contributor teams. That actually doesn't seem to have translated into a state of outdatedness anywhere near the levels we saw with the Codex.
  • The Code Reference is parsed from the source code and supplemented by additional information and examples submitted and voted upon by a vibrant community of everyday WordPress users (we just passed 2,000 user contributed notes!)
  • Phase II of HelpHub will bring improved search capability and a user feedback mechanism not currently available anywhere else on .org other than on DevHub

In any regard, if the final unified portal (hopefully there is only one) is going to be called "DevHub" than a subdomain like "dev.wordpress.org" might make more sense (and better URLs/SEO)...

#3 @littlebizzy
9 months ago

This is being worked on, as a matter of fact, the HelpHub articles that have been copied from codex went live yesterday. Phase two of HelpHub work is starting, which is not fully defined.

Unfortunately this reinforces the point, as most users (us included) don't know what this means...


@DrewAPicture Thanks for the detailed background, a response:

In the span of five or so years, It's gone from a very centralized, albeit unmaintainable, state to a largely fragmented one, as you've alluded.

Indeed, the fact that it's taken 5+ years to copy paste articles to a new subdomain, all the while with no explanation to end users, is perhaps illustrative of the ongoing stalemate.

If the issue is that the word "Codex" is too limiting, why couldn't the subdomain simply be renamed? And while the Codex has definitely been neglected, what's the difference between the Make/Docs team investing time into revamping the Wiki content, as opposed to copying the content into a new centralized system that adds even more bureaucracy and inefficiency to WordPress.org than it already suffers from? How can anyone contribute?

...but more importantly, why would anyone want to contribute to that? E.g. If some genius PHP developer finds something wrong in the new docs, how many hoops, teams, and (maybe) power-tripping moderators must he now go through just to let the WordPress community know about some urgent discovery?

See, on a team such as docs – where participation wildly ebbs and flows – there is a persistent need for additional help.

This is precisely why it should remain a Wiki-style, public contributions platform.

Not advocating for you to throw away what's been accomplished -- in fact, the new Support articles look really nice and seem easier for newbies to browse than Forums.

However, keeping a Docs Wiki seems like the right move for long-term. Happy to help re-format and re-write.

Or, perhaps just the Code/Function Reference could be non-Wiki format?

Yes, by virtue of becoming authoritative, the documentation is now largely uneditable (at least directly) by anyone outside the contributor teams. That actually doesn't seem to have translated into a state of outdatedness anywhere near the levels we saw with the Codex.

But it will, inevitably. Except this time, the public can't fix it.

However, if the private silo goes forward, why doesn't the WP Foundation hire paid staff to maintain it?

DevHub: https://developer.wordpress.org
HelpHub: https://wordpress.org/support
Making WordPress: https://make.wordpress.org/

Hmm, a proposal:

  • Docs = docs.wordpress.org
  • Support = wordpress.org/support/
  • Contribute = wordpress.org/contribute/

Ultimately, shifting all documentation to a centralized silo might work in the long-term if a for-profit company with a department lead was at the helm. But as it were, WordPress.org functions more like committees of rotating volunteers, which is why documentation should encourage public contributions as much as possible...

"Committees kill unconventional ideas for a living."

― Mokokoma Mokhonoana

#4 @DrewAPicture
9 months ago

  • Resolution set to worksforme
  • Status changed from new to closed

As always, processes and progress are works in progress. Everyone here is a volunteer, and if you'd like to contribute, there are plenty of channels by which to do that, this being just one.

If you'd like to constructively propose changes to how documentation on .org is structured, that is best left to the open floor portion of a docs team meeting (meeting times and locations in the make/docs sidebar).

Meta Trac is used for actionable proposals, and as this ticket apparently serves more as a list of grievances than constructive proposals I'm going to close it. Thank you for the feedback, it has been noted.

Version 0, edited 9 months ago by DrewAPicture (next)

This ticket was mentioned in Slack in #docs by kenshino. View the logs.


9 months ago

#6 @DrewAPicture
9 months ago

@littlebizzy After thinking about it a little bit, I recognize that I sort of slammed the door in your face by closing the ticket here. Note: tickets don't need to remain open for discussion to continue.

I recognize there can sometimes be a feeling of powerlessness when it comes to decision-making on .org.

All of the people who are participating in the decision making for things like docs or meta were users when they started and are still users today. These are people who found something frustrating or broken or in need of help and decided to pitch in to make them better. The decision-makers are people who built up a reputation for consistently doing good work and have thusly been rewarded with community trust.

None of the decisions currently driving docs team priorities on .org were taken lightly; all of them were weighed and considered and discussed in public spaces long before implementation began.

So while the basis of several of your points are valid, the shape of your arguments lend a sense of aggressiveness that doesn't come across as particularly constructive or useful at this stage in the process. Things like renaming subdomains or completely overhauling the base approach are pretty much non-starters. Could have, would have, should have. We devised a roadmap and it's guided our approach pretty well so far.

Shutting off edit in the Codex at some point is a very real possibility and will probably happen sooner than later now that HelpHub Phase I has been launched. We were in a crunch to get it launched in time for WordPress 5.0 so Gutenberg user docs would have a place to live.

We could be better about making feedback mechanisms both more available and transparent. If you're interesting in helping make that a reality, we'd love to have you.

If I might give some advice to you as a new contributor in this space, it would be to give greater consideration for how your arguments come across going forward. We operate in the open here, and coloring arguments with hyperbole – like reducing five years of work writing, editing, and rewriting thousands of pages of docs to copying and pasting from one place to another – isn't going to advance positive discussion forward.

It's OK to be frustrated, welcome to the club. We're all here to make WordPress documentation better. There's always things and processes we can improve, but it's a team effort.

Last edited 9 months ago by DrewAPicture (previous) (diff)

#7 @littlebizzy
9 months ago

  • Resolution worksforme deleted
  • Status changed from closed to reopened

After thinking about it a little bit, I recognize that I sort of slammed the door in your face by closing the ticket here. Note: tickets don't need to remain open for discussion to continue.

Appreciated, it's also closing the door to the entire community who might feel the same way.

None of the decisions currently driving docs team priorities on .org were taken lightly; all of them were weighed and considered and discussed in public spaces long before implementation began.

That doesn't mean the decisions were the best (or permanent?).

We never saw any public discussion, polls, or otherwise... your meetings are not public. We are pretty "high tech" but couldn't figure out how to join your meetings, others probably feel the same.

So while the basis of several of your points are valid, the shape of your arguments lend a sense of aggressiveness that doesn't come across as particularly constructive or useful at this stage in the process. Things like renaming subdomains or completely overhauling the base approach are pretty much non-starters. Could have, would have, should have. We devised a roadmap and it's guided our approach pretty well so far.

If these grievances are valid, why are you shutting down the ticket?

Aggressive mistakes require aggressive fixes, sometimes. Let's focus on improvement, egos aside...

We encourage you to launch a public poll re: this discussion, we know a good poll tool.

It's OK to be frustrated, welcome to the club. We're all here to make WordPress documentation better. There's always things and processes we can improve, but it's a team effort.

Except it won't be a team effort in the near future...

Because WordPress.org is a community, and because tickets are an important part of that community, I'm reopening this ticket because we have the ability to do so. You've not allowed anyone else to comment yet, nor have you considered any of our stated proposal(s).

Already 6 people are following this ticket, which shows great interest. Thanks ~

#8 @Kenshino
9 months ago

  • Keywords close added
  • Resolution set to invalid
  • Status changed from reopened to closed

Hey! I'm Jon, the Docs' Team lead and for the sake of clarity, Drew is the previous Docs' Team lead and an advisor of sorts and does know what he's talking about :)

We never saw any public discussion, polls, or otherwise... your meetings are not public. We are pretty "high tech" but couldn't figure out how to join your meetings, others probably feel the same.

Our meetings are public on Slack and usually have meeting notes written up within the week. The meeting agenda and notes are free for commenting on make.wordpress.org/docs

HelpHub meetings have been going on semi-regularly for 2 years before 2018 and weekly in the year 2018. I do think we've given anyone who's interested in the ecosystem plenty of time to participate :)

If you feel differently, I encourage you to join Slack and have a chat with us.

As you might have noticed, there are a few people following and all of them are people who are directly responsible for the HelpHub project and none of them were Docs Team members before they joined and push the project along.

They joined #docs, voiced their thoughts and participated in a manner that was helpful to the rest.

And with such - as @DrewAPicture said, trac tickets are really not for such discussions. Come to #docs if you want more visibility. (6 here vs 1302 in Slack)

Btw you said "we", do bring any others along :)

#9 @littlebizzy
9 months ago

  • Resolution invalid deleted
  • Status changed from closed to reopened

@Kenshino Thanks for commenting --

Because these issues still stand and are waiting for resolution, I'm reopening this ticket again.

Please do not close this ticket until there is resolution on these WP.org items:

  1. misleading callout on the Codex site
  2. disable editing on the Codex if it will be shut down
  3. notify Wiki contributors their copywriting will be stripped of attribution and repurposed (illegal, btw)
  4. consolidation of portals/URIs
  5. *long-shot* seek community feedback before finalization

Perhaps for once, a WordPress.org discussion can result in solutions, not power-trips...

#10 @littlebizzy
8 months ago

Further research shows discussion over the lack of Docs clarity goes back to at least 2005:

https://codex.wordpress.org/IRC_Meetups/2005/May

WordPress Site identity/unification. Can we have everything under the wordpress.org site? Like Codex as is or docs.wordpress.org or wordpress.org/docs and wordpress.org/faqs or faqs.wordpress.org, developing a core "brand" site location? Lorelle 03:42, 24 May 2005 (UTC)

Everyone seems to agree "Codex" is a goofy name that needs to retire.

Personally, I wouldn't even mind the "Developer" landing page (subdomain) if it wasn't trying to replace what should be a Documentation portal, especially by [illegally] repurposing copyrighted copywriting from the Wiki. If it wants to be a landing page with curated content, so be it, but there should remain a community-style Wiki unless Docs contributions are going to be readily accepted and/or paid staff are going to be updating it daily.

Comparing some of the closest OSS projects:

https://docs.joomla.org
https://developer.joomla.org

https://docs.magento.com
https://devdocs.magento.com

https://www.drupal.org/documentation

https://laravel.com/docs/

https://docs.craftcms.com

https://wiki.simplemachines.org

https://dev.wix.com/docs/

https://developers.squarespace.com

https://dev.weebly.com

https://i.imgur.com/B2IbPp6.png
(via Google Trends)

#11 @Kenshino
8 months ago

  • Resolution set to invalid
  • Status changed from reopened to closed

Thank you for the research.

I'll bring this up with the team when the opportunity arises and if it's relevant.

Note: See TracTickets for help on using tickets.