[TYPO3-core] [Wrap-up] Workflow for changing documentation

[Xavier Perseguers]

Hi,

As discussed yesterday during our doc-team meeting [1], Francois asked
me to prepare this wrap-up.


tl;dr
-----

- We should move official manuals to Github in order to simplify the
contribution workflow, by adding a "edit me on github" button/link on
each chapter

- Was inspired by many projects having this workflow. Just an example
with elasticsearch [2] and Fluid Power TYPO3 [3].

- Patch for our template to include the "edit" link is to be found in
message [4]


Rationale
---------

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

- Git is fully decentralized, meaning we would not be stuck with some
provider if we want to move away at some time since our tight would be
limited to a link we generate to fork and contribute

- Pull-requests and Gerrit workflows are fundamentally different, so one
cannot compare them in regard to the other, the point is that
pull-requests (used by Github) are much easier to grab and deal with by
newcomers since next to no Git knowledge is required.


How it would work
-----------------

- 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 "Edit me on Github"


Pros gathered in the discussion
-------------------------------

- Frans Saris: "I'm for moving the docs to a place where everybody can
easily contribute [...] sometimes I'm tempted to go to
http://translation.typo3.org/ and fill in some translations. How cool
would it be if I could just enhance the docs in a same way"

- Markus Klein: "Sounds good. At least we should try it out. We can go
back to the "old" system anytime if we think we have to."

- Steffen Müller: "That would definitely be an improvement, especially
for minor changes"

- Philipp Gampe: "Online editing would make things easier for beginners,
but keep in mind that they need a github account to do so. From a
developers point of view, the github editing is definitely nice. If
our target group for editing doc changes are devs (at least I think so),
then we should give github a try for the more technical manuals."

- Fedir Rykhtik: "Great idea!"


Cons gathered in the discussion
-------------------------------

- Jigal van Hemert: "Fine, if Github supports a SSO with t3o. [...] I
still feel we should offer all the tools needed in the t3o environments
instead of moving things to platforms we have zero control. [...] For me
personally it's that if I want to contribute in some way to TYPO3 I do
it with an account on t3o. If documentation is hosted on github I will
be limited to filing issue to forge."

- Jigal van Hemert: "We already see it with code that forks are spread
all over the web and people hardly know which version is "real". [...]
Even if we remove it from our github account there will still be many
copies floating around. These are all indexed and will show up in search
results. [...] extensions and other code teams such as the security team
cannot remove unsafe versions, especially because so many copies would
be readily available."

- Philipp Gampe: "The documenation will look official on all forks, but
is not. It will even state that it is official documentation. If we have
some unsecure example in any version of the documentation, then it will
be hard to get rid of this."


Links
-----

[1] http://forge.typo3.org/projects/team-docteam/wiki/2014-05-19

[2]
http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/_why_we_wrote_this_book.html

[3] http://fluidtypo3.org/documentation/templating-manual/introduction.html

[4] http://forum.typo3.org/index.php?t=msg&th=203589&goto=710286&#msg_710286


-- 
Xavier Perseguers
TYPO3 CMS Team Member

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