Monday, June 27, 2016

Guided DITA Authoring Solution Overview

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

We've had past blog posts about how Oxygen can be used to impose various editing behaviors for your team. In this blog post, we are going to try to bring all of these solutions together in a comprehensive overview.

Learning to Work with DITA and Oxygen

You can find useful links for learning to edit DITA using Oxygen in this previous blog post: http://blog.oxygenxml.com/2016/03/resources-for-learning-dita-with-oxygen.html.

Migrating to DITA

There are multiple reasons why you would want to migrate from unstructured content to structured: http://blog.oxygenxml.com/2015/12/migrating-to-structured-standards-based.html.

This older blog post details some possibilities of migrating Word documents to DITA: http://blog.oxygenxml.com/2016/05/how-to-migrate-from-word-to-dita.html. You also have ways to migrate from XML-based standards (like DocBook or XHTML to DITA) using a set of predefined transformation scenarios.

Implementing Your own Style Guide

Let's say you are a team of technical writers collaborating on a DITA-based project and suppose that you have your own various best practices in regards to which elements to use and when to use them. So, at some point you gather a set of HTML resources that explain how various DITA elements should be used, you store them on an internal server, and you want all your team members to have access to that set of HTML resources directly from Oxygen. This blog post provides more details and useful links to help you get started: http://blog.oxygenxml.com/2016/03/implementing-your-own-style-guide.html

Imposing Controlled Attribute Values

If you want to impose DITA attribute values that need to be set for profiling or general use, this blog post should cover all you need to know about this: http://blog.oxygenxml.com/2015/07/controlled-attribute-values-for-your.html

Restricting the Visual Editing Experience

The entire visual editing experience using the Author editing mode in Oxygen is CSS driven. Oxygen has support for defining various CSS layers that can be applied when editing DITA content. For example, if you choose to create a Lightweight DITA topic in Oxygen, it has a special editing layer that allows it to be edited with a combination of buttons, hints, and form controls.

Imposing Business Rules and Structure Restrictions to the DITA Content

In most cases, instead of relying on people to memorize numerous internal documentation style rules, you can convert many of these rules to Schematron and allow the application to automatically signal the content author when a rule is violated. You can also add quick fixes to show authors various ways to rectify the problem. This blog post contains more details about this: http://blog.oxygenxml.com/2015/05/schematron-checks-to-help-technical.html.

Running Batch Validation Checks on all of Your DITA Content

The Validate and Check For Completeness tool available in the DITA Maps Manager view performs a lot of different consistency checks on all your DITA topics. It can also be used to apply Schematron business rules on all of your topics: http://blog.oxygenxml.com/2015/12/dita-map-validate-and-check-for.html.

Sharing DITA Editing Customizations with Your Team

Most of the custom editing behaviors, toolbar, and menu buttons that are available when editing DITA content are defined in the DITA framework configuration. A framework configuration's general anatomy is described here: http://blog.oxygenxml.com/2014/08/the-oxygen-sdk-part-2-frameworks.html.

The framework configuration can be shared with all of your team members. For example, here is a way to restrict team members from using certain DITA elements: http://blog.oxygenxml.com/2015/08/document-type-extension-sharing.html. Furthermore, here is a way to distribute new DITA file templates to your team: http://blog.oxygenxml.com/2015/12/sharing-new-custom-file-templates-for.html.

Sharing Global Application Settings with Your Team

Let's say you want all of your team members to enable the automatic spell checker when writing documentation, or you want all of them to use a custom term dictionary or a custom set of learned words. This older blog post offers some hints about how global Oxygen settings can be distributed to your team members: http://blog.oxygenxml.com/2015/11/sharing-application-settings.html.

Collaboration, Content Management, and Version Tracking

All major Component Management Systems (CMSs) have plugins that can be installed in Oxygen to provide access to the CMS: https://www.oxygenxml.com/partners.html#cmssolutionpartners. Even if you lack the funds to buy a commercial CMS, there are still plenty of open source version tracking solutions that allow collaboration for a single DITA project: http://blog.oxygenxml.com/2013/12/collaboration-teams-working-on-common.html. For example, the Oxygen User's Manual is written in DITA and we use a GitHub private repository to collaborate on it: http://blog.oxygenxml.com/2014/11/collaboration-for-documenting-software.html.

Allowing Subject Matter Experts to Review Content

Many technical writers are interested in having their content reviewed by the subject matter experts who are directly involved in building the tools. Oxygen has support for change tracking and adding comments directly in the edited content. Subject matter experts do not necessarily need to have the standalone version of Oxygen installed. The Oxygen Web Author is an online editing and reviewing solution that allows them to add comments and propose changes directly in the DITA content by using any device with a web browser (laptop, tablet, phone): https://www.oxygenxml.com/xml_web_author.html.

I hope this overview will help you to implement a complete guided authoring experience using Oxygen. As usual, if you have any questions or suggestions, they are welcome.

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!

Guided Authoring: Enforcing Editing Rules

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Webinar - Guided Authoring:
Enforcing Editing Rules

This webinar presented a way of imposing various rules that your content authors need to follow, such as grammar rules, document structure guidelines, business requirements, style preferences, or rules for the generated output. 

When editing documents there are various rules that you want your content authors to follow, such as grammar rules, document structure guidelines, business requirements, style preferences, or rules for the generated output. To enforce these rules, companies often use grammar checking apps, custom schemas or best practice guides.

For content authors, there are usually too many rules to remember them all when writing content. The best approach for this challenge is to signal the user when a rule violation is detected and offer suggestions to help them solve possible rule problems and maintain integrity in their documentation.

A recording of the event, sample files, and slides are available on our website: 








Discover the technology behind the fix proposals for business rules by attending our next webinar: Understanding and Developing Schematron Quick Fixes - Jul 14, 2016

Tuesday, June 14, 2016

DITA-OT Day 2016

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
Oxygen XML Editor is happy to organize the 3rd edition of the DITA-OT Day event, which will take place this year in Munich, Germany, on November 13:
https://www.oxygenxml.com/events/2016/dita-ot_day.html

This is a great chance to meet the main DITA-OT developers, Jarno Elovirta and Robert Anderson, as well as other contributors and users of the most used project in the DITA community!

More, there is no registration fee, it is a free event!
Because lunch and coffee breaks are provided, we need to know how many of you will be there, so registration is required:
https://www.oxygenxml.com/events/2016/dita-ot_day.html#dita-ot2016_registration

The DITA-OT Day shares the same location as DITA Europe, the Hilton Munich City hotel, and it takes place the day just before DITA Europe.  It is also two days after the TCWorld conference, which takes place in Stuttgart, so it is very convenient to attend DITA-OT Day if you also plan to go to DITA Europe or/and TCWorld.

We are working on putting together the agenda for this year and we are collecting proposals for interesting topics. If you want to contribute please submit a proposal as described at:
https://www.oxygenxml.com/events/2016/dita-ot_day.html#dita-ot2016_proposals

If you did not attend the DITA-OT Day event before, check out the agenda and recordings of the previous events:
https://www.oxygenxml.com/events/2015/dita-ot_day.html
https://www.oxygenxml.com/events/2014/dita-ot_day.html

Hope to see many of you at DITA-OT Day 2016!
George

Wednesday, May 25, 2016

How to Migrate from Word to DITA

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
The need for migrating Microsoft Office® Word documents to XML formats, and particularly to DITA, is quite a frequently encountered situation. As usual, migration from proprietary formats to XML is never perfect and manual changes need to be made to the converted content. However, the methods below should help you find the best approach for your particular case:

 Method 1
  1. Open the Word document in MS Office, select all the content, and copy it.
  2. Open Oxygen and create a new DITA topic in the Author visual editing mode. 
  3. Paste the selected content. Oxygen's smart paste functionality will attempt to convert the content to DITA.
Method 2
  1. Save your MS Office Word document as HTML.
  2. Once you obtain that HTML, you have two possibilities:
    • In Oxygen, Select File->Import->HTML File to import the HTML as XHTML. Then open the XHTML in Oxygen and in the "Transformation Scenarios" view there should be four pre-configured transformation scenarios to convert XHTML to DITA topics, tasks, references, or concepts.
    • Open the HTML file in any Web browser, select all of its content, and copy it. Then open Oxygen, create a new DITA topic in the Author visual editing mode, and paste the selected content. Oxygen's smart paste functionality will attempt to convert the HTML to DITA.
Method 3
  1. Open the Word document in the free Libre Office application and save it as DocBook
  2. Open the DocBook document in Oxygen.
  3. Run the predefined transformation scenario called DocBook to DITA.
Method 4
  1. If the Word document is in the new DOCX format you can open it in Oxygen's Archive Browser view and then open the document.xml file contained in the archive.
  2. Run the predefined transformation scenario called DOCX DITA. This ANT scenario runs the following build file: OXYGEN_INSTALL_DIR/frameworks/dita/DITA-OT/plugins/net.sourceforge.dita4publishers.word2dita/build-word2dita.xml over the DOCX archive and should produce a DITA project that contains a DITA map and multiple topics. 
  3. You may need to do some reconfiguring to map DOCX styles to DITA content. 
Note: This method may also be helpful if you want to run it automatically with scripts, since it is based on the DITA OT and DITA For Publishers plugins.

Monday, May 16, 2016

Upcoming DITA Webinars

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr
In the next few months we will host a series of DITA-related webinars that will cover almost every aspect of working with DITA in oXygen XML Editor. The first 3 webinars are scheduled as follows:
  1. Getting started with DITA using oXygen XML Editor
    Thu, May 26, 2016 8:00 AM - 9:00 AM PDT
    This webinar will focus on introductory concepts of working with DITA documents in oXygen XML Editor, covering everything from creating DITA maps and topics from scratch to basic publishing using out-of-the-box transformation scenarios. You will also learn how to edit simple topics, create cross references, insert images and tables, and how to benefit from intelligent features such as smart paste or validate and check for completeness.
    You can register to attend at https://attendee.gotowebinar.com/register/8739574101053242114
  2. DITA reuse and filtering
    Thu, Jun 30, 2016 8:00 AM - 9:00 AM PDT
    This webinar will focus on advanced features that justify your return on investment from using DITA. REUSE is the key word and it can be implemented either directly through content references or indirectly through profiling/conditional content.
    You can register to attend at https://attendee.gotowebinar.com/register/6779464826612680193
  3. DITA publishing with oXygen XML Editor
    Jul 28, 2016 8:00 AM - 9:00 AM PDT
    In this webinar, we will explore DITA publishing options available in oXygen XML Editor to produce and customize various output formats such as WebHelp, HTML, PDF, or EPUB.
    You can register to attend at https://attendee.gotowebinar.com/register/7133519665384504065
After these 3, we plan to host 4 more webinars that will cover:
  • The support for the new DITA 1.3 standard in oXygen XML Editor.
  • How you can use oXygen XML Web Author to enhance collaboration between contributors and reviewers.
  • A detailed look into how you can maintain the integrity of your DITA maps and topics by using the validate and check for completeness feature, as well as imposing various editing rules.
  • How we create the oXygen User Guide, set up our workflow, enforce project-specific rules, and publish our documentation.

If you want us to cover other DITA-related topics in these webinars, please use the Comments section to let us know.
See you soon!

Friday, May 13, 2016

Collaboration and Document Review in Oxygen XML Editor 18

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr

Collaboration and Document Review in Oxygen XML Editor 18

The reviewing process involves a continuous interaction between authors, reviewers, and subject matter experts.
The visual Author mode now allows you to collaborate more easily and effectively with others through comment threads by providing a new reply to comment action and allowing you to mark comments as being resolved.

Reply to comments

You can collaborate with other members of your team more easily, taking advantage of the improved annotation support. You can now reply to comments added by others and you can also start new comment threads. Everyone that has access to the project can see the comment threads and join the discussion at any time.

Mark as done

The Mark as done option allows you to mark a discussion thread as being completed. This is useful for marking comments that have been addressed, leaving only those that still need some attention.


Watch the following video to see more about Collaboration and Document Review in oXygen XML Editor 18:

Friday, May 06, 2016

XML Three Way Diff in Oxygen XML Editor 18

Share to Facebook Share to Twitter Email This Share on Google Plus Share on Tumblr


The new XML-aware three-way file comparison feature helps you solve conflicts and merge changes between multiple modifications of the same file. It is especially helpful for teams that have multiple authors working concurrently on the same documents.


Three-Way File Comparison Support
A three-way file comparison feature was added to the file comparison tool to help you solve conflicts and merge changes between multiple modifications.
 It is especially helpful for teams who have multiple authors editing and committing the same documents. It provides a comparison between a local change, a remote change, and the base (ancestor) revision.

Multiple Algorithms for Three-Way Comparisons
You can use Lines, XML Fast, and XML Accurate algorithms for the three-way comparison feature in the file comparison tool and in the Compare view in Syncro SVN Client.
  • Lines - Computes the differences at line level, meaning that it compares the files looking for identical lines of text.
  • XML Fast - Works well on large files or fragments, but it is less precise than XML Accurate.
  • XML Accurate - More precise than XML Fast, at the expense of speed and memory. It compares two XML files or fragments looking for identical XML nodes.

Integration with version system
The Files Comparison tool can be integrated with file versioning systems in order to visualize changes in a side-by-side manner ans solve conflicts.
Second-Level Comparison
The File Comparison tool now automatically performs a second level comparison for the Lines, XML Fast, and XML Accurate algorithms. After the first comparison is finished, the second level comparisons are processed on text nodes using a word level comparison, meaning that it looks for identical words. This second level comparison makes it easier to spot precise differences and you can merge or reject the precise modifications.


Ignore Nodes by XPath Option
A new option was added on the toolbar of the File Comparison tool and in the Compare view in the Syncro SVN Client. You can enter an XPath 2.0 expression to ignore certain nodes when comparing using the XML Fast or XML Accurate algorithms.



This demonstration will show you how the oXygen three-way comparison feature works and how you can use it with file versioning systems.