Monday, June 20, 2016

Enable Massive Contributions with oXygen XML Web Author and GitHub

Early in 2016, a new product was added to the oXygen XML set of tools - the oXygen XML Web Author. It leverages the power of oXygen XML Author (which basically runs on the server side) and provides access to XML authoring from any modern device that supports a browser capable of rendering HTML5+JavaScript, including desktops and mobile devices like your smart phone or tablet.

The real power of web-based XML authoring can be seen when it is integrated as part of a workflow, simplifying it by reducing a large number of steps to just a few. This is what the GitHub connector provides!

If you have XML content on GitHub, you can then provide a link that will open a file in the oXygen XML Web Author and anyone will be able to review or edit it just by accessing the link and saving (a GitHub account is of course required).

When you save a file, assuming you do not have commit access on that repository, the GitHub connector will automatically:
  • fork the project into your account, if it is not already
  • create a new branch from the edited branch
  • commit your changes on this newly created branch
  • create a pull request from your newly created branch to the originally edited branch
  • switch the editor to your branch so further save operations will just add new commits to your branch, thus updating the pull request with new changes
This is a great simplification of the contribution process, a contributor just follows a link and saves the file, and all the magic to create the pull request happens automatically.

If the XML source is published, then it is possible to include an "Edit this page" link on the published format that will allow immediate access to the editor. An example of such access is provided for the DITA-OT documentation project. The development branch is published at http://www.dita-ot.org/dev/ and every page contains an "Edit this page" link at the bottom that gives immediate access to the DITA topic that page is generated from.

For example, the http://www.dita-ot.org/dev/user-guide/DITA_v1-3-support.html page shows the DITA 1.3 support in DITA-OT and the "Edit this page" link will send you to the DITA_v1-3-support.dita topic. If you edit a file and then save it, a pull request with your changes will be automatically generated. Content contribution cannot be easier than this!

Next, we plan to have the "Edit this page" link available in every page of the oXygen documentation, which is also hosted on GitHub at https://github.com/oxygenxml/userguide.
Hope you find this useful!

No comments:

Post a Comment