VideosImproving documentation review workflows using Oxygen XML Web Author

Overview

This video presents some real world use-cases for using Oxygen XML Web Author to improve documentation quality, team efficiency, and the review process.

Transcript

00:00:07The main purpose of this video is to demonstrate some real world use-cases where Web Author
00:00:12is used to improve documentation quality, team efficiency, and the review process.
00:00:18Web Author is a web-based XML authoring tool.
00:00:22It's a lightweight version of Oxygen XML Author that can be used on any device that includes
00:00:28a modern web browser and from anywhere you have internet access.
00:00:33The first use-case involves a situation where a proofreader or support engineer notices
00:00:38problems in the documentation and they want to streamline the documentation workflow by
00:00:43proposing changes or adding comments directly in the XML source.
00:00:48The documentation team can then easily integrate the changes or suggestions without various
00:00:53additional steps being required somewhere in the process.
00:00:57I will show you how they could use Web Author to achieve this.
00:01:02Suppose I'm a proofreader and I'm using PDF output to review a topic about "Migrating
00:01:07MS Office Documents to DITA".
00:01:09I notice that the 3rd method is missing a step in the procedure.
00:01:15We've configured our PDF output to include an "Edit" link so I can simply click that
00:01:21link... ...and the document is now opened in Web Author.
00:01:25More about Web Author in just a minute, but let's also explore another similar possibility.
00:01:31Suppose I'm a support engineer and I've received feedback from a user that they were experiencing
00:01:36issues trying to migrate Office documents to DITA.
00:01:39I have found this same topic in our WebHelp version of the documentation and I want to
00:01:45send them a link to it...
00:01:47...however, I also notice that the 3rd method is missing a step and even though I could
00:01:52just explain this to the user, it would obviously be better if this was corrected in the documentation
00:01:58before sending it to the user.
00:02:00We've also configured our WebHelp system to include the "Edit" link, so similarly I can
00:02:06simply click this link... ...and the document is opened in Web Author just like the first scenario.
00:02:13If you're familiar with Oxygen XML Author or Editor, you'll notice that Web Author has
00:02:18a lot of the same basic editing functionality.
00:02:22Suppose I want to add a step in the procedure for Method 3.
00:02:25I can simply position the cursor at the end of the list item where I want to add a new
00:02:30one and click the "insert list item" button on the toolbar.
00:02:35I'll enter the text for the new step... ...and I also noticed another potential problem
00:02:41and want to add a comment for the documentation team.
00:02:45I'll select the content and click the "Add Comment" button from the toolbar...
00:02:50I'll enter my comment...
00:02:54Notice that my comment now appears in the "Review" panel on the right.
00:02:59Now I just need to save my modifications.
00:03:02In our case, we've integrated Web Author with a Git repository so I can simply select "Commit"
00:03:09from the Git drop-down menu or by using CTRL+S.
00:03:13Note that you can integrate Web Author with a variety of repository services, not just Git.
00:03:19Once the document is saved into the repository, the documentation team can also see the changes
00:03:24in Oxygen XML Author (or Editor), assuming they have access to the repository.
00:03:31Some of the benefits of using Web Author for this type of use-case are:
00:03:36- It provides a very quick way for a proofreader or support engineer to edit or suggest changes
00:03:42in the documentation.
00:03:44- Content is continually improved through contributions by the proofreaders or support engineers.
00:03:50- The review and contribution process is streamlined and fewer steps means less potential for mistakes.
00:03:57The second use-case involves a common scenario where a Content Author has created a document
00:04:02and wants to send it to a subject matter expert for review to make sure it's accurate and
00:04:07they want changes or comments to be added in the XML source document so that they can
00:04:12easily merge the changes back into Oxygen XML Editor or Author.
00:04:17Again, I'm going to show you how Web Author can be used for this.
00:04:21There are obviously numerous ways that a document can be sent to others, but for our case, we
00:04:26are using a collaboration solution called Oxygen Content Fusion.
00:04:30If you're not familiar with Content Fusion, it's a collaboration tool that makes the entire
00:04:34documentation review process very simple and efficient.
00:04:39The Content Author just creates a review task and sends a link to the subject matter expert...
00:04:46who simply follows the link to open the document in Web Author.
00:04:50Notice that in this case, the Web Author is integrated inside the Oxygen Content Fusion interface.
00:04:58Note that Web Author can also be integrated as a component in various other solutions.
00:05:02Now, suppose I'm the reviewer and I just want to make a few minor changes to the title.
00:05:08Note that this integration forces the "Track Changes" feature to be enabled so that the
00:05:13Content Author will know exactly what was modified and they can easily accept or reject each change.
00:05:20This makes collaboration very simple and efficient.
00:05:23Now the Content Author just needs to be notified of the changes so they can integrate them
00:05:27into their project in Oxygen XML Editor or Author.
00:05:32In our case, Content Fusion notifies us and helps us to automatically merge the changes
00:05:36back into Oxygen XML Editor.
00:05:39Some of the benefits of using Web Author for this type of use-case are:
00:05:45- It's a very simple and efficient way to collaborate.
00:05:48- It provides an incremental review workflow that is more likely to engage reviewers and
00:05:52lead to more feedback.
00:05:55- It allows the Content Author to control the published content while the Reviewer simply proposes changes.
00:06:02The third use-case involves a scenario where someone in a documentation team creates a
00:06:06template for knowledge base articles, contributors from multiple off-site locations use this
00:06:13common template in Web Author to create articles, and these articles then comes back to the
00:06:19documentation team in the same format regardless of where they come from, so it's very easy
00:06:24for them to integrate the articles back into their project in Oxygen.
00:06:27This can be achieved by guiding the contributors with form controls built into the template
00:06:31and I'm going to show you how this can be done in Web Author.
00:06:35Suppose that someone has created a template for a knowledge base article submission form
00:06:41and all contributors have access to this same template, regardless of where they are located.
00:06:46All they have to do is fill out the form in Web Author.
00:06:49Notice that the template contains simple form controls to guide the contributor.
00:06:54Now the contributor just needs to save it in Web Author and the documentation team can integrate it
00:07:00into their knowledge base project in Oxygen XML Editor or Author.
00:07:11Some of the benefits of using Web Author for this type of use-case are:
00:07:16- There is a small learning curve since contributors are guided by familiar form controls.
00:07:21- Content remains in XML format so there's no conversion necessary.
00:07:26- It helps to maintain consistency among multiple contributors.
00:07:32These were just some of the many possible use-cases for using Web Author.
00:07:36It can be integrated into virtually any type of workflow.
00:07:40I'm sure you are already thinking about ways to integrate Web Author in your workflows.
00:07:46We encourage you to contact us with the details of your specific requirements so that we can
00:07:51provide you with more specific suggestions.
00:07:55This concludes the demonstration.
00:07:56Thank you for watching.