[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