[TYPO3-core] Workflow for changing documentation

[Frans Saris]

I'm for moving the docs to a place where everybody can easily contribute.

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.

My use-case :)

It is a sunny sunday sitting in my garden enjoying the weather and reading
some stuff on my tablet.
Now 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.

Just an idea

gr. Frans


2014-05-05 9:12 GMT+02:00 Xavier Perseguers <xavier at typo3.org>:

> 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
>
> _______________________________________________
> Before posting to this list, please have a look to the posting rules
> on the following websites:
>
> http://typo3.org/teams/core/core-mailinglist-rules/
> http://typo3.org/development/bug-fixing/diff-and-patch/
> _______________________________________________
> TYPO3-team-core mailing list
> TYPO3-team-core at lists.typo3.org
> http://lists.typo3.org/cgi-bin/mailman/listinfo/typo3-team-core
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.typo3.org/pipermail/typo3-team-core/attachments/20140505/2194df29/attachment-0001.htm>