Do Technical Writers Dream of Arbortext Editor?

For the first time in my technical writing career, I have been getting hands-on experience with PTC Arbortext Editor and the Darwin Information Type Architecture (DITA) standard. Wild stuff, you guys.

For those of you who don’t know, Arbortext Editor is a software program that lets you do “structured writing“—a special kind of writing in which every piece of content you compose follows one or more specific rules, or what tech comm guru Mark Baker calls “predefined and explicitly recorded constraints”. For example, a rule might be that all of your procedural content must conform to a particular sequence: title, short description, index terms, introduction, steps, links to related topics, and so on. Another rule might be that all steps in a procedure must be numbered, and that bullets cannot be used for steps. Theoretically, by adhering to these rules, you and colleagues are more likely to produce content with a consistent pattern and level of detail.

Does that sound boring and confusing to you? I get it. The tool is mainly for technical writers. If that’s not you, I would back away slowly and never come here again.

For the handful of brave individuals who are left: below is my brief wishlist of things I’d like to see improved in Arbortext (I’m using release 7.0), with the goal of providing some insight into how the tool works and potentially informing your decision on whether or not to adopt it. Note that I’ve limited my observations to basic authoring functionality, which means I don’t get into things like style sheets and multi-format publishing. Also, as a novice user, I may well be missing some key information. If you’re an Arbortext power user and know of a simple solution for any of the items below—emphasis on *simple*—please leave a comment and let me know.

With that, let’s dive in.

My Arbortext Wish List

1. A modern look and feel.

Although Arbortext lets you do sophisticated DITA authoring, the skin of the program is an banal throwback to Windows 95. Getting excited about structured authoring is hard enough. Why not overhaul the appearance altogether and help writers feel a little better about their lives?

Yes, anyone can find something to criticize in a software tool’s outward appearance. But this seems especially important to me for at least two reasons. The first is usability. As Donald Norman reminds us in The Design of Everyday Things, things that look better are generally easier to use. The second is competitive edge. Other authoring tools that are popular among technical writers—Microsoft Word, MadCap Flare, Adobe RoboHelp, Atlassian Confluence—have made good strides in this area, and I think it’s time for Arbortext to catch up.

“But wait,” you might say, “those other tools aren’t specifically designed to support DITA or structured writing, so it’s not fair to compare them to Arbortext.” That’s true in a way, and it may explain why Arbortext hasn’t done much to change things on this front. Arbortext addresses a niche problem, and there aren’t that many competitors to threaten its growth. (I believe the closest competitor is Oxygen Editor, which in my opinion has the better look and feel, though not in a dramatically significant way.)

I’m no product manager, but I don’t think that’s an especially good business reason not to innovate on this dimension of the product. A better UX is, well, a better UX; and a better UX usually means increased adoption and fewer support costs. But whether or not the makers of Arbortext will prioritize that investment … I’m not holding my breath.

2. Automatic reference updates.

In MadCap Flare, the main way you develop documents is by building an outline file that consists of individual HTML topic file references. If you change the name or location of any of the referenced files, you can automatically update them wherever they’re used so that they don’t break. The same goes for Confluence. Assuming you are using relative rather than absolute URLs, moving and renaming a wiki page is a relatively painless task.

Unfortunately, in Arbortext, a reference will break anytime you change its name or folder location, and the program will throw disgusting error messages.

Now, you can use Arbortext’s Update References feature to get 20% of the way to a solution. For example, if you edit a DITA topic title, but keep the file name and location the same, then you can use the Tools > Update References feature to sync your DITA map with the edited title. But this feature doesn’t sync with file name or location changes. Which is onerous and sad.

3. An easy way to see linked files.

Let’s say I want to know all the places where a given file, image, or piece of content is linked to or referenced in other files. Does Arbortext support that?

Sort of, but not really. The best solution that the Arbortext support team could give me to this scenario was to use the built-in Find Tag/Attribute feature. But that isn’t a super helpful workaround because it’s time-consuming and you can only jump to one instance of your linked file at a time, and it works best if you happen to know the referenced file’s name or unique ID that you’re looking for.

The far better solution here would be to right-click a file and have a View Links option, similar to what MadCap Flare can do. Or perhaps a Page Information feature like in Atlassian Confluence, which lets you view a complete list of incoming and outgoing links. Either way, I’d like to see this information readily available at the click of a button.

4. Improved notifications for invalid markup.

One major issue I had with Arbortext was discovering some invalid DITA markup only after our document build process broke. One of my colleagues traced the problem back to the fact that content references to tables in Arbortext do not carry over all the required elements of a <table> tag from the source file to the target file.

This seemed very odd to me, so I dug a little deeper and learned that if I manually run the Check for Completeness feature in Arbortext, an error message will in fact appear to indicate that there is a problem. But this sort of issue should be highlighted as soon as it occurs rather than waiting for the user to manually run a checker. In the Oxygen Editor, for example, any issues with invalid markup are immediately flagged with warnings or squiggly underlines. I think that’s what Arbortext needs, at least in this particular case of table content references.

5. Tabbed topics rather than separate windows.

Want to open or create a new topic in Arbortext? You get a brand new window. Want to open 10 new topics? Ten new open windows it is—even if each topic is only a paragraph or two long.

That’s way too many windows.

Granted, this is the same behavior in tools like Word, Confluence, and Google Docs. But in the case of browser-based editing tools, you can arrange your documents in tabs and toggle between them. In addition, we generally expect documents to be longer than topics, so it’s easy to understand why a tool like Microsoft Word doesn’t employ a tabbed design. You usually don’t need to open ten or more Word documents at a time because most of the content you are working with is somewhere in a single document.

By contrast, in Arbortext you are encouraged to create relatively short and self-contained topics, and you often need to open a lot of topics at once to make edits across them. Which means generating a separate window for each one feels like considerable overkill.

To me the solution is easy: just go the route that MadCap Flare has gone and provide topic tabs within the frame of the application.

6. Simple paragraph returns.

If you press enter or return to insert a paragraph break in Arbortext, you will be disappointed. Or rather, interrupted. Instead of getting an actual paragraph return, you are shown a “Quick Tags” menu. The default option is generally the one you want (either a para split or a p split), but the fact that you have to confirm that default every time you want to start a new line is soul-crushing absurdity.

You could argue that the menu is a nice forcing function because the writer must think carefully about what type of content is coming next. But why not just assume it will be a plain new paragraph and let the writer easily change it later if necessary?

7. An out-of-box preview button.

Anyone who writes or designs content for end users knows how important it is to check the output of your content before you officially publish it. That’s what a “preview” function is for, and most if not all content tools I know of provide this ability in their core offering. Arbortext Editor, however, does not. (From what I can tell, you need to purchase an additional module called “Print Composer” to generate previews.) To me this is a needless, staggering oversight.

You can of course get close to a preview. Arbortext has what’s called a “Resolved Document” feature that compiles all of your individual topics into a temporary, editable version of your document. However, it’s not a preview in the truest sense: the document uses a bunch of default styles, which 99% of the time are not the styles you would see in your final document when your CSS stylesheet is applied. Why not just make the preview function available in the base license without requiring users to pay more for such a standard feature?

Is there anything good about Arbortext?

I’ve ranted a lot here, but Arbortext isn’t all bad. One of its best features is the Resolve Document for Editing feature, which (as I mentioned briefly above) lets you do is scoop up all the topics in your DITA map and assemble them in a temporary document so you can see all of your topics in context and edit them for flow and consistency. The really cool thing is that your edits will be saved to the corresponding source files.

It’s important to realize a few limitations, though. One, this feature is best for previewing linear print documents that are read from top to bottom. Don’t expect it to do a good job of emulating an online help system. Two, it’s more for self-editing than for peer review. Any changes that a peer makes in this view won’t be tracked, which would be a problem if you happen to disagree with the changes and need some trace-ability. So don’t use this feature for a peer review unless your peer is doing light edits that you’re not concerned about verifying.

Does a tool like MadCap Flare have anything comparable to this? Well, Flare does have a robust set of review functions, as well as an easy way to generate a Word document for editing purposes. The major drawback in that case is that you still have to incorporate any edits back into the source files in Flare. You could “link” the Word document to Flare so that any edits you make to the former will filter into the latter, but setting up this link requires a time-consuming document import process. Arbortext’s “Resolve Document” function is a faster and easier way for authors to simulate their print content and implement changes directly in the source files.

Of course, the other noteworthy strength of Arbortext Editor is really its main strength: its DITA-based document templates. You can easily create a DITA task, concept, or reference topic with all the right tags in place, and get straight to filling in those tags with your amazing prose. If DITA is the primary authoring model at your organization, it’s worth taking a close look at Arbortext and comparing it to other DITA authoring tools like Oxygen Editor. I haven’t done an exhaustive comparison with Oxygen, but if I did I would look at how Oxygen handles the gaps I’ve described above.

Conclusion

Maybe some technical writers dream of Arbortext Editor. I don’t, and not just because of its cosmetic shortcomings. It’s simply missing a lot of crucial time-saving features that I’ve grown so accustomed to seeing in other tools. While it may be one of the leading products in the DITA-based structured writing niche, I would thoroughly investigate the alternatives before buying it.