[wp-meta] [Making WordPress.org] #7520: Move Handbooks to GitHub to ease ability to contribute content

[Making WordPress.org]

#7520: Move Handbooks to GitHub to ease ability to contribute content
-----------------------------+---------------------
 Reporter:  oglekler         |       Owner:  (none)
     Type:  feature request  |      Status:  new
 Priority:  normal           |   Milestone:
Component:  Handbooks        |  Resolution:
 Keywords:                   |
-----------------------------+---------------------

Comment (by dd32):

 Replying to [comment:2 bsanevans]:
 > In the Training Team, many of the contributors are not developers, and
 are therefor not familiar with the concept of creating PRs, or maintaining
 documentation in GitHub. For these reasons, updating the handbook in the
 Editor would seem to be “easier” for this team.

 I think this is the bigger problem, using GitHub for documentation is
 "easier" for a segment of the user-base, but it's not accessible to all,
 nor is it clear to many how it will look after converting markdown to
 WordPress Blocks ''(and Markdown is something that some absolutely love,
 and others absolutely hate)''. It works great for some documentation (ie.
 Block Editor, the docs and code changes can happen in the same Gutenberg
 PR) but can be total shambles for other content.

 I don't personally see a problem with GitHub PRs as a way to manage
 suggestions, but I wish those suggestions didn't have to be managed via a
 GitHub account and PRs on markdown. ''Especially when WordPress is a
 CMS.''

 Using GitHub for handbooks is more of a workaround for the underlying
 issue of "WordPress.org doesn't have a way for users to offer textual
 edits and suggestions for content", without giving someone literal write
 access to an entire site.

 The complication, is that while we could theoretically enable wiki-like
 functionality for WordPress.org handbooks and pages, teams and
 stakeholders would require/demand an approval flow and without a system in
 place to enable fast enough approvals of those suggestions, a wiki-system
 wouldn't exactly work.

 To add to that though, this also brings with it some caveats for future
 translatability of the content, while it's easy enough to say "It's better
 for translators, they can fork it and create a new version!" that isn't
 ideal to keeping the translated form updated with new english changes,
 there needs to be a single source-of-truth that translations are based
 off. Gutenberg Phase 4 (Multilingual WordPress) will be reliant upon
 having WordPress posts as the source-of-truth, and managing the content
 outside of WordPress is going to create future work to support that.

 '''tl;dr:''' Simply converting handbooks to GitHub "to make contributions
 easier" isn't easier for all, and causes other problems IMHO.


 This is all to say; While GitHub offers some benefits to some, can we
 consider if it's actually the ideal solution before just accepting it as
 the solution?

 Perhaps this is a situation where some teams could brainstorm or
 collaborate on new approaches?

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