Writing documentation in an interactive world: Some thoughts on using easyDITA and OxygenXML
Since moving to DITA, I've tried to settle on best practices and determine the authoring method that works best for me. I started out using OxygenXML, which is one of the most popular DITA editors. I like OxygenXML because it's easy to work with the code. OxygenXML knows when to show you a list of all possible elements or values you can insert in your topic at any time.
For example, if you type 
But the challenge with any DITA text editor, whether you're using OxygenXML, XMetal, XML Mind, or some other, is reviewing content with others. (Oxygen is actually developing a web app that allows others to review content. You put your content on Google Drive or Dropbox as a source repository. The web app then pulls in the content and wraps it in a design that includes buttons for annotation and review. I saw a brief demo and liked the direction it was going, but I needed something more immediately functional and robust.)
Knowing that easyDITA has a good system for review, I started a trial and uploaded my content there. I also used the webdav connector within OxygenXML to edit the content on easyDITA. The webdav data source connector is a neat little tool within OxygenXML that makes it easy to edit remotely stored content.
While it's relatively easy to switch editors between OxygenXML and easyDITA as I work on the same content, depending on what I wanted to do, I found myself gravitating more and more toward easyDITA for several reasons. Primarily, I like to make a lot of comments on documentation as I go through it. Many of the comments are my own notes (such as "need to verify if this code is up to date..."). But I also gave my team access to review the content as well. A number of SMEs have logged in as reviewers and poked around, though I've yet to see an actual comment from them (the real review cycle hasn't actually started).
There's a problem, however, in switching back and forth between editors. OxygenXML's comments don't appear in easyDITA, and easyDITA's comments don't appear in OxygenXML. Only if you use the element, the comment appears inline with the text rather than in the margins, which makes comment interfere with the flow of the text.
Since I want to see both my comments and SME comments, I decided to prioritize the easyDITA comments and started working more in the easyDITA editor.
As I worked more in the easyDITA editor, I also noticed a couple of other things. First, I really don't miss working so closely with the code. While in OxygenXML I regularly switched between Text and Author mode, with easyDITA I only go into the source view if I've managed to mess something up. It's still helpful to know DITA from a code level, because it means I can troubleshoot problems and I understand how things should fit together.
But it's easier to focus on the content when I see it in a rich text view. The content view in easyDITA is aesthetically rich and pleasing to read. The content looks really sharp. When SMEs review the content, they're also looking at a crisp, easy-to-read, rich view of the content.
As long as I know what tags go where, the elements I can insert, the attributes and properties, working in easyDITA is more comfortable for me because I focus on the content more. And I'm less likely to actually write invalid code. I still like having OxygenXML as a fallback to fix code if I need it, or to do something more advanced, but I'm now using easyDITA more as my primary authoring editor rather than just as a review platform (which is why I initially started my trial).
Despite the aesthetically pleasing content view, there are stronger reasons for using an online platform like easyDITA. When you write in an XML format like DITA, you face a huge challenge with content review and interactivity. It's okay to start authoring DITA content in an editor on your machine, but if you want to produce good technical content, you need other team members to review it. Other tech comm team members, QA team members, product managers, engineers, support engineers, and field engineers -- everyone should be able to freely review the content.
Each team member will have a different perspective that he or she brings to the content. An engineer who wrote code for integrating a feature in Android will have a different perspective from a QA person who tested the configuration options in Java, just as a field engineer might be curious how a certain situation is handled with Websphere servers instead of Tomcat, for example. A product manager might have a lot more to say about product overviews and feature descriptions.
To think that I can write even a 100 page manual in isolation that nails each of these points dead on is naive. And if I need the feedback of team members around me to be successful, how can I keep the content in a closed silo, editing away on a local editor?
If I author all my content in a local editor, how exactly do others review it in a continuous way? There aren't many options. Distributing a PDF, printing something out, or maybe having a SME look over my shoulder are about all the possibilities out there. (I suppose I could get about 5 floating OxygenXML licenses, have everyone install OxygenXML and connect with webdav to get at the content, but I doubt they'd do that.)
At my previous company, I authored content in Google Docs (before publishing to Drupal) primarily for the interactivity with team members. It worked brilliantly, too. Engineers, product managers, and others engaged abundantly with comments. But with DITA, unless I wanted to try porting the help content to Google Docs and back (which is a content trip that doesn't work), I'm stuck. That's why I really like the idea of easyDITA. It provides the benefits of a wiki-like platform, or a Google Docs-like platform, but with DITA content. Being able to bring that interactivity to help content in its draft mode is empowering.
I have to say that I also like authoring in the browser. As a blogger who has been on WordPress for 8 years, I feel at home in browser-based applications. It feels very twenty-first century and modern. I can sit down at any computer with Internet access and start working on my content. If my computer crashes (or more likely, if I crash on my bike and my computer gets damaged), I'm not worried about losing content.
I know easyDITA's interface has some areas that definitely could use improvement. But knowing that they're working on a major overhaul of their interface, one that will soon be cross-browser compatible, as well as other online help output solutions, gives me sense that the platform must be gaining momentum.
I have had somewhat limited exposure to DITA editors. I have only briefly tried XML Mind and XMetaL, and haven't interacted with other browser-based editors. So I apologize for focusing on just two products here. But I hope that my message has been less about this or that tool and more about the need for interactivity with other team members when writing documentation.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.