[wp-meta] [Making WordPress.org] #3972: Lack of clarity re: various documentation portals

[Making WordPress.org]

#3972: Lack of clarity re: various documentation portals
-------------------------+---------------------
 Reporter:  littlebizzy  |       Owner:  (none)
     Type:  enhancement  |      Status:  new
 Priority:  normal       |   Milestone:
Component:  Codex        |  Resolution:
 Keywords:               |
-------------------------+---------------------

Comment (by DrewAPicture):

 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
 [https://make.wordpress.org/docs/2013/06/19/docs-sprint-results-and-
 roadmap/ 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)...

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

-- 
Ticket URL: <https://meta.trac.wordpress.org/ticket/3972#comment:2>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org