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

Making WordPress.org noreply at wordpress.org
Mon Dec 3 09:47:09 UTC 2018


#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 littlebizzy):

 > 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

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


More information about the wp-meta mailing list