Using GitHub for Collaborative XML Publishing
Authoring a technical standard can distract from the development of the standard’s content. Equipping a standards committee effectively to satisfy the documentation obligation, without impacting on the technical development, benefits those involved and produces results faster.
And writing is not the only task. Assembling complex work products can be finicky, and so leveraging automation where possible produces results more consistently.
This case study shows how two OASIS technical committees collaboratively prepare documents for both OASIS and ISO submission.
The committees’ goals were to:
- maximize the time developing technical content, which is why the members joined in the first place;
- minimize the time spent formatting content twice to satisfy two sets of layout requirements;
- automate the production of intricate committee deliverables; and
- enable committee members to propose contributions to the editors in an efficient manner.
This case study illuminates the committees’ use of DocBook XML for authoring a single document to produce multiple layouts. Moreover, using XML provides options for generated content not readily available in other authoring environments.
Also illustrated is how the editing and publishing process is supported by using the git repository and GitHub hosting for collaborators to use to make their proposed contributions to the editors. Together with the online XML publishing service from Réalta, this equips members to preview their draft work in final-form PDF and HTML at any time. This frees members of the burden of supporting specialized, expensive publishing tools they may not otherwise need.
The end result for each committee is the hands-off production of complete work product deliverables including two different PDF layouts.
IMPORTANT: This essay is not intended to replace the more detailed README.md instructions for the technical committee members found in their respective git repositories. Rather than get bogged down in details, this essay is meant to introduce and overview the strategy of using git and GitHub for collaborative committee work.
Technical note
This monolithic HTML document includes embedded SVG graphic images that may not be visible on all browsers. The author has tested this file successfully on Chrome, Firefox, Opera, Edge, and Safari.