The Documentation Team wishes to test a new, simpler way of contributing to the TYPO3 manuals. This article first provides some background information and then details on this proposed contribution process. For those who are in a hurry, let's start with a quick summary.
Summary
The Documentation Team is now providing a Github mirror of the TypoScript Reference (TSref) for a trial phase. Just fork it and make pull requests. If accepted, your requests will be ported to the official repository.
Some background
The migration of TYPO3 documentation to a text-based format (reStructured Text) has made it far easier for people to modify an existing manual and has enabled the Documentation Team to go through a review process similar to the one for code patches. The recent TYPO3 CMS development cycles have seen an increased number of developers actually providing documentation patches to follow up on code patches. In turn this made it possible for the Documentation Team to provide up to date manuals in a timely fashion, despite very limited manpower.
It is however still difficult for many people to contribute to the documentation, as some quite technical skills are required. The manual must be fetched from its Git repository, a hook for the Gerrit review system must be installed, then the changes needs to be committed and pushed. All this is far from trivial, especially for people who may have never used a version control system, or the command line, or any other tool generally used by developers. This clearly poses restrictions on the pool of people who can contribute.
Looking at other projects it appeared that using a Github hosting was advantageous in that regard since files can be edited online even with some syntax highlighting (thanks to the support for Markdown, a precursor of reStructured Text). The idea was thus floated to host our manuals on Github and a long debate ensued (<link http: forum.typo3.org index.php t>read the full discussion). The summary is that we really want to stick to our Forge/Git/Gerrit combination which provides an excellent workflow in terms of integration and quality control.
So we came up with the idea of having Github mirrors, which anyone could fork and submit pull requests to. The accepted changes would be ported to the official repositories by the Documentation Team and - at regular intervals - the Github mirrors would be restored to keep in sync with changes in the official repositories. How does this work for you, dear potential contributor?
How to contribute
We are now opening a trial phase for this new process. The most popular TYPO3 CMS manual will be used for this test: the TypoScript Reference (TSref). It is now available at the following address:
<link https: github.com typo3-documentation typo3cms-reference-typoscript>
github.com/TYPO3-Documentation/TYPO3CMS-Reference-Typoscript
Just connect to Github. If you don't have an account yet, create one, it's free. Go to the above URL and click on the "Fork" button. Github will work for a while and then provide you with your own copy of the TSref. You can edit any file. Once you're done, Github will ask you if you want to make a "pull request". This means submitting your changes for approval to the reference repository. That's it. You can sit back and wait for feedback from the Documentation Team. Or edit more files and submit more pull requests.
Take a look at this short video for getting started quickly: <link https: vimeo.com>
vimeo.com/77629277
We expect the trial to last a couple of months. We will then assess if it's worth continuing and expanding this process, depending on the amount of contributions received.
