[TYPO3-core] Workflow for changing documentation

[Xavier Perseguers]

Hi,

Starting a thread in this list instead of the standard documentation
list to gather more feedback on an idea floating in the air since many
months.

tl;dr
-----

- We should move official manuals to Github in order to simplify the
contribution workflow
- Let's discuss that, pros and cons


Background
----------

- Updating the official manuals/guides/... (TSref, Core API, Beginner
Guide, ...) requires:

	- Spotting a problem by reading
	- Filling a ticket on Forge
	- Cloning a Git repository (one has to find which one)
	- Finding the place in the documentation, fixing/enhancing it
	- (Damn!) Configuring Git to contribute to TYPO3
	- Pushing to Gerrit
	- Not speaking about amending patch after comments are made

For Active Contributors and other "power users", this is still quite
some work. I experienced it myself a few weeks ago where I was tempted
to simply "forget about it" since I would have loved simply clone and
push a nobrainer without even a ticket.


Fact
----

- Gerrit is great for our our codebase but much too complicated for
newcomers which could however be exactly targeted at easily providing
feedback on our doc to enhance it

- GitHub's (Bitbucket's / Gitlab's / ...) pull request workflow would be
much easier to use

- Git unlike SVN is fully decentralized, meaning we do not have to fear
anything using another platform to "host" the code since

	- Everyone having a clone has the full history
	- Idea is not to tie us to any external service, just make use of it
"out-of-the-box" and switch back/further whenever we think it's needed
	- git.typo3.org may easily read-only mirror any external repository if
we would feel safer this way, just as
https://github.com/TYPO3-extensions/ is doing the other way around


Proposal
--------

- Move every official documentation (we may start with 3-4 to start
with) to Github
- Remove the requirement for a ticket on Forge when it comes to
day-to-day change but *keep it* when it comes to documenting some change
in the Core API (e.g., new feature)


Rationale
---------

- Let's take an extension of mine, namely "sphinx" that is already
mirrored to Github (discovered that recently):

https://github.com/TYPO3-extensions/sphinx/

tree/master/Documentation/Introduction

Say someone wants to update the introduction chapter, it's just a matter
of browsing to
https://github.com/TYPO3-extensions/sphinx/tree/master/Documentation/Introduction
and clicking on "Index.rst"

which redirects to
https://github.com/TYPO3-extensions/sphinx/blob/master/Documentation/Introduction/Index.rst

>From there one can see the chapter in her browser rendered as HTML
(cool) and sees a "Edit" button which will automatically fork the
repository. From there, you /may/ edit the file and create a pull
request without ever leaving your browser.

=> The whole workflow is straightforward for everyone, including people
having little to no clue about Git.

=> The edit link is like that:
https://github.com/TYPO3-extensions/sphinx/edit/master/Documentation/Introduction/Index.rst
meaning we could relatively easily directly link to it from any page on
docs.typo3.org, as many other projects already do, with a big button
similar to "Enhance me on Github"


Other ideas
-----------

I would have a few other (I guess cool) ideas about this process but
let's defer that to later :)


-- 
Xavier Perseguers
TYPO3 CMS Team Member

TYPO3 .... inspiring people to share!
Get involved: http://typo3.org