How to Setup DITA XML Project using Oxygen XML Author and GitHub?

If you’re a product or service-based company, whether small, medium or large scale, chances are you publish your technical documentation through various platforms like MS Word, Git Wiki, and more. However, if you implement DITA XML writing for your project, you’ll need an XML authoring and publishing platform, as well as an efficient collaboration platform for the writers, reviewers, and contributors. This is where Oxygen XML Author and GitHub come in.

Oxygen XML Author for Editing and Publishing

Oxygen XML Author is a favorite choice for Technical Writers when it comes to progressing with their DITA XML Technical Documentation project. Not only does it provide features such as visual editing, information structuring, document structure validation, and content completion, but the Oxygen Publishing Engine also enables teams to publish DITA XML content to PDF, Web Help, and many other formats right from inside the application.

GitHub for Content Management and Review

Meanwhile, GitHub is a widely used code hosting platform that is well-known for version control and collaboration. It’s an ideal platform for storing DITA topics and managing issues or reviews (tickets) as a workflow for your documentation project. When used together with Oxygen XML Author, GitHub can provide an efficient and streamlined process for managing and reviewing technical documentation.

By leveraging the power of Oxygen XML Author and GitHub, small, medium, and large-scale product or service-based companies can enjoy a scalable solution for their technical documentation needs. They can achieve better collaboration, version control, and content management, all while saving on costs.

Following is the procedure to learn more about how you can leverage Oxygen XML Author and GitHub together to replace a DITA topics CMS and enjoy cost benefits.

Prerequisites

Style Sheet and Template

• [.css] Page, Chapter and Section numbering (TOC and Content)
• [.css] Formatting the document content (header, font, color and alignment etc.)
• [. opt] Publishing template for output formats (style sheets, params for output formats)

Software Licenses and User Accounts

• Oxygen XML Author – Desktop (Edit and Publish)
• GitHub – Desktop (Manage content and Collaborate)

Initial Setup

• Set up a GitHub repository for your DITA XML Documentation projects.
• Install Git (Git Staging) add-on – Oxygen XML Author desktop (Integrate GitHub Repository).
• Define GitHub workflow.

Getting Started with GitHub, Git Add-on (Git Staging) and
Oxygen XML Author

Flow Diagram

• [GitHub] Set us your GitHub account and access GitHub.
• [GitHub] Set up your Doc repository to store and manage the DITA projects and content.
• [GitHub] Set us your team from the organization for review, edit and contribution through GitHub.
• [GitHub] Set up your project structure feasible for the DITA XML project. Such as, ‘Reusable Content’, ’Templates’, ‘Document/Product Specific’, ‘Graphics’ and other.
• [Oxygen XML] Create or edit your DITA content in Oxygen XML Author.
• [Oxygen XML] Configure the Oxygen Publishing Engine with the Style Sheets and templates before publishing.
• [Oxygen XML] Run the transformation and publish the content to the required format.
• [Oxygen XML] Install and Git Add-on and content to your Git repository.
• [Git Add-on] Open Git Staging and clone your documentation git repository to your local.
• [Git Add-on] Open Git Staging and commit and Push the output and source files from your local to Git repository.
• [GitHub] or [Git Add-on] create a Pull Request (PR) to initiate the DITA topics content review.
• [GitHub] performs review and share feedback or propose changes.
• [GitHub] or [Oxygen XML] Implement the review feedback and cross-check.
• [Oxygen XML] Run the transformation and publish the content to the required format (again).
• [Git Add-on] Open Git Staging and make a new commit and Push to the Git repository.
• [GitHub] Do final check, approved and merge the source files and output to Master.
• [GitHub] Release the approved document.

Hope you enjoyed the reading. Please share your views and find similar interesting topics on our BLOG page.