<div dir="ltr">I'm for moving the docs to a place where everybody can easily contribute.<div><br></div><div>Would be even more cool if you have some system (like now for translations) where you can just contribute by editing some text somewhere on a website.</div>
<div><br></div><div>My use-case :)</div><div><br></div><div>It is a sunny sunday sitting in my garden enjoying the weather and reading some stuff on my tablet.</div><div>Now sometimes I'm tempted to go to <a href="http://translation.typo3.org/">http://translation.typo3.org/</a> and fill in some translations.</div>
<div><br></div><div>How cool would it be if I could just enhance the docs in a same way. </div><div><br></div><div>Just an idea </div><div><br></div><div>gr. Frans</div></div><div class="gmail_extra"><br><br><div class="gmail_quote">
2014-05-05 9:12 GMT+02:00 Xavier Perseguers <span dir="ltr"><<a href="mailto:xavier@typo3.org" target="_blank">xavier@typo3.org</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
Hi,<br>
<br>
Starting a thread in this list instead of the standard documentation<br>
list to gather more feedback on an idea floating in the air since many<br>
months.<br>
<br>
tl;dr<br>
-----<br>
<br>
- We should move official manuals to Github in order to simplify the<br>
contribution workflow<br>
- Let's discuss that, pros and cons<br>
<br>
<br>
Background<br>
----------<br>
<br>
- Updating the official manuals/guides/... (TSref, Core API, Beginner<br>
Guide, ...) requires:<br>
<br>
- Spotting a problem by reading<br>
- Filling a ticket on Forge<br>
- Cloning a Git repository (one has to find which one)<br>
- Finding the place in the documentation, fixing/enhancing it<br>
- (Damn!) Configuring Git to contribute to TYPO3<br>
- Pushing to Gerrit<br>
- Not speaking about amending patch after comments are made<br>
<br>
For Active Contributors and other "power users", this is still quite<br>
some work. I experienced it myself a few weeks ago where I was tempted<br>
to simply "forget about it" since I would have loved simply clone and<br>
push a nobrainer without even a ticket.<br>
<br>
<br>
Fact<br>
----<br>
<br>
- Gerrit is great for our our codebase but much too complicated for<br>
newcomers which could however be exactly targeted at easily providing<br>
feedback on our doc to enhance it<br>
<br>
- GitHub's (Bitbucket's / Gitlab's / ...) pull request workflow would be<br>
much easier to use<br>
<br>
- Git unlike SVN is fully decentralized, meaning we do not have to fear<br>
anything using another platform to "host" the code since<br>
<br>
- Everyone having a clone has the full history<br>
- Idea is not to tie us to any external service, just make use of it<br>
"out-of-the-box" and switch back/further whenever we think it's needed<br>
- <a href="http://git.typo3.org" target="_blank">git.typo3.org</a> may easily read-only mirror any external repository if<br>
we would feel safer this way, just as<br>
<a href="https://github.com/TYPO3-extensions/" target="_blank">https://github.com/TYPO3-extensions/</a> is doing the other way around<br>
<br>
<br>
Proposal<br>
--------<br>
<br>
- Move every official documentation (we may start with 3-4 to start<br>
with) to Github<br>
- Remove the requirement for a ticket on Forge when it comes to<br>
day-to-day change but *keep it* when it comes to documenting some change<br>
in the Core API (e.g., new feature)<br>
<br>
<br>
Rationale<br>
---------<br>
<br>
- Let's take an extension of mine, namely "sphinx" that is already<br>
mirrored to Github (discovered that recently):<br>
<br>
<a href="https://github.com/TYPO3-extensions/sphinx/" target="_blank">https://github.com/TYPO3-extensions/sphinx/</a><br>
<br>
tree/master/Documentation/Introduction<br>
<br>
Say someone wants to update the introduction chapter, it's just a matter<br>
of browsing to<br>
<a href="https://github.com/TYPO3-extensions/sphinx/tree/master/Documentation/Introduction" target="_blank">https://github.com/TYPO3-extensions/sphinx/tree/master/Documentation/Introduction</a><br>
and clicking on "Index.rst"<br>
<br>
which redirects to<br>
<a href="https://github.com/TYPO3-extensions/sphinx/blob/master/Documentation/Introduction/Index.rst" target="_blank">https://github.com/TYPO3-extensions/sphinx/blob/master/Documentation/Introduction/Index.rst</a><br>
<br>
>From there one can see the chapter in her browser rendered as HTML<br>
(cool) and sees a "Edit" button which will automatically fork the<br>
repository. From there, you /may/ edit the file and create a pull<br>
request without ever leaving your browser.<br>
<br>
=> The whole workflow is straightforward for everyone, including people<br>
having little to no clue about Git.<br>
<br>
=> The edit link is like that:<br>
<a href="https://github.com/TYPO3-extensions/sphinx/edit/master/Documentation/Introduction/Index.rst" target="_blank">https://github.com/TYPO3-extensions/sphinx/edit/master/Documentation/Introduction/Index.rst</a><br>
meaning we could relatively easily directly link to it from any page on<br>
<a href="http://docs.typo3.org" target="_blank">docs.typo3.org</a>, as many other projects already do, with a big button<br>
similar to "Enhance me on Github"<br>
<br>
<br>
Other ideas<br>
-----------<br>
<br>
I would have a few other (I guess cool) ideas about this process but<br>
let's defer that to later :)<br>
<br>
<br>
--<br>
Xavier Perseguers<br>
TYPO3 CMS Team Member<br>
<br>
TYPO3 .... inspiring people to share!<br>
Get involved: <a href="http://typo3.org" target="_blank">http://typo3.org</a><br>
<br>
_______________________________________________<br>
Before posting to this list, please have a look to the posting rules<br>
on the following websites:<br>
<br>
<a href="http://typo3.org/teams/core/core-mailinglist-rules/" target="_blank">http://typo3.org/teams/core/core-mailinglist-rules/</a><br>
<a href="http://typo3.org/development/bug-fixing/diff-and-patch/" target="_blank">http://typo3.org/development/bug-fixing/diff-and-patch/</a><br>
_______________________________________________<br>
TYPO3-team-core mailing list<br>
<a href="mailto:TYPO3-team-core@lists.typo3.org">TYPO3-team-core@lists.typo3.org</a><br>
<a href="http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-team-core" target="_blank">http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-team-core</a><br>
</blockquote></div><br></div>