Edit online

Contributed by: Radu Coravu on 2020-01-21

There are many cases in which a handful of technical writers in a company need to collaborate on a DITA project and they may not have the resources to invest in an open source content management system. So this blog post is about setting up a viable, cost efficient DITA documentation editing and publishing solution which can scale up (both in number of writers and content) using Oxygen XML Author and Github. As a showcase for the proposed solution we will have the Oxygen XML Blog.

Overview of Tools Proposed for the Solution

The same set of tools has been used for editing and publishing the Oxygen XML Blog: Welcome to the Oxygen XML Editor Blog !.

Learning DITA

There are various online resources for learning DITA, there are also learning DITA courses held by consulting companies. This older blog post has some useful links: Resources for learning DITA with Oxygen.

Project Storage - Using GitHub

You need a system to:
  • Store your DITA content.
  • Collaborate with your colleagues on writing content in the same project.
  • Allow for reviewers to propose changes without having the right to commit changes.
  • Have a history of changes on each DITA resource, being able to revert to previous versions of topics.
  • See who changed what content in each DITA topic and map.
  • Be able to tag releases so you can build manuals for older releases with some changes applied to them.
  • Maintain a list of issues which are closed as your work progresses.

Some small teams instead of using a version control system resort to shared network drives. Shared network drives do not address all the features above and they are dangerous in the fact that you can overwrite other people's work and there is no way to revert changes.

A free Github account can cover all these use cases listed above. GitHub exposes through a web interface access to a Git repository. This blog post is not about learning Git, it's about having minimum Git skills to get you started. There is a good book about learning Git Here: https://www.manning.com/books/learn-git-in-a-month-of-lunches.

We'll outline below some steps to get you started with a GitHub project:
  1. Create a GitHub account: https://github.com/join.
  2. Create an organization: https://github.com/settings/organizations. The organization will be useful to group work-related projects.
  3. Add your team members to the organization. Using the team member GitHub user names you can send them invitations to be contributors to the project.
  4. Create a new repository in the organization for your project. For creating private repositories you will need to switch to a paid plan. The alternative is to create a new private repository in your own account.

Creating and Modifying Content in the Repository

You can create and edit DITA topics in a number of ways:
  • Edit topics offline and use GitHub's user interface to upload it, or modify existing topics using GitHub's web interface.
  • Use the Oxygen Web Author to connect to the Git Repository and create a new topic or modify an existing one.
  • Clone the repository to the local file system using Oxygen XML Author with the Git Add-on installed.

Using Oxygen XML Author to Create/Modify Content in the Repository

  • Install the Git Add-on in Oxygen XML Author.
  • Open the Git Staging view and use the + toolbar button to paste the reference to the reference to your project, for example https://github.com/oxygenxml/blog.
  • Choose a location on the local drive where the project will be cloned.
  • The Git Staging view does not show all existing resources in the project, it will just show the modified resources, so go to the Project menu and create a new Oxygen project in the folder where the project was cloned.
  • In the Git Staging view the newly created project.xpr should now appear. Select it, use the Stage Selected button to stage it, then write a commit message and use the Commit message to commit it. Now the file is committed in your local repository. You can use the toolbar Push button to push it to the GitHub account.
  • Create a DITA Map and a couple of topics using Oxygen's Project view.
  • Using the same Git Staging view you can see the newly added files, stage, commit and push them to the remote GitHub repository. You can check on the remote GitHub repository that the files were updated.
  • If changes are made by someone else using the same technique or if changes to maps and topics are made directly from the GitHub web interface or from the Oxygen WebAuthor, the Git Staging view has a Pull toolbar button allowing you to obtain those changes locally.
  • On resources which have been modified a number of times you can right click in the staging area and choose Show in history to see a history of changes. You can also choose Show blame to see who modified each of the lines in the document.
Here's a simplified overview of how you could work with Oxygen and Git:
  • Every time you start Oxygen or every time before you commit use the Pull toolbar button from the Git Staging view to get changes locally.
  • Stage and commit your changes, then push them to the remote repository.
  • If you attempt to pull changes including a file which is already modified locally by you, the pull operation will not succeed. You will need to copy that file separately, pull the content from the server and then compare your changes to the ones coming from the server and merge your changes.
  • If you have already committed to your local repository a resource modified also on the remote repository, you have a conflict, the Git Staging view allows you to edit the conflict, merge the changes locally and then commit to the local repository and push changes to the server.
  • You do not have to pull and push changes from and to the remote repository very often, you can continue working with your local repository for days and push all changes at the end but not pulling changes from the server often might result in various conflicts if the same resources are modified both on the server and in your local repository.

Working with Branches

You may need to mark releases of your product and also to be able to contribute small fixes to those releases. So here's how you work with branches:
  • The default branch in the project is called master and this is the branch we've been working until now.
  • Using GitHub's web interface you can create your own branch.
  • Check out again in the Git Staging view the project, this time with the separate branch in a separate folder.
  • Open the project.xpr from that branch's checkout, make changes to the content there, stage, commit and push as usual.

Organizing Your Project Structure using the Master Files Support

You can now start to organize your content.

You can right click the Project root and enable master files, then in the Master Files folder add a reference to the main DITA map (or maps). All refactoring operations (move resources to subfolders, rename topics or resources) will properly update references in the entire DITA project hierarchy.

Sharing Common Settings using the Project

The Oxygen project configuration can save various sets of global options at project level. As an example:
  • Go to the Oxygen Preferences->Editor / Spell Check page and change the radio button at the bottom to Project Options. Then check the Automatic spell check checkbox.
  • The Git Staging view should have a modified version of the XPR showing as modified, stage, commit and push it.
  • Now everybody using the same project.xpr project file loaded in Oxygen will have spell check enabled.
Other useful settings you could switch to Project Options:
  • The Project Level Settings preferences dialog allows you to control if various settings are saved at project or global level. For example you can save the Validate and check for completeness settings at project level and share them with others.
  • The Editor / Spell Check / Dictionaries preferences page can contain your own set of dictionary terms.
  • The Document Templates preferences page allows you to use your own custom new file templates.
  • In the Editor / Save preferences you can save at project level various save options.
  • Switching the Menu Shortcut Keys preferences page to project level allows you to share with others custom menu shortcut keys.