In 2005, I presented a paper at the Annapolis Content Management Strategies conference on a DITA editor evaluation heuristic entitled "Selecting an Authoring Tool for DITA — More than Just Another XML."  The presentation explained a way to assess DITA capabilities in editors that were then emerging in the marketplace.  Its time to revisit that heuristic, as many editors now meet the basic qualifications for DITA awareness.

Basics for XML editors

It's something you do without thinking much about it--whenever you need to operate a car that is new to you, you instinctively know where to find the blinkers, the lights, the brake and gas pedals, and so forth. Likewise you should also be able to open up any XML editor candidate and find it able to support some basic editor capabilities. This list can be as detailed as you wish, but ultimately it will be uneven across editors and you'll have to accept some compromises.

No duh, an XML editor should provide a way to validate your markup. Rather than run a validation check from time to time, the best editors will provide live validation as you type, and will only allow you to insert new markup where it is valid (as opposed to validation AFTER creating possibly invalid markup changes).

You would also expect your XML editor to support undo, cut/paste and common keyboard navigation shortcuts and selection behaviors. I list these behaviors mainly for completeness, but you want to be sure your writers don't have an "uh-oh" moment every time they try to jump back to the top, for example!  Are the key assignments what you expect them to be? Can you reconfigure them?

Level of the bar in 2005

As I said in 2005, "XML editors are readily available in both free (often Open Source) and commercial implementations, built to suit a variety of XML tasks from authoring data packets to book-length manuscripts. There are many that are at least somewhat suitable for writing DITA topics, but how can you find the one that is best for you? The heuristic approach described in this presentation will point you quickly to the class of editors that are best for your DITA authoring requirements."

The ultimate goal in 2005 was that an editor must be DITA-aware, meaning that it supports the key DITA architectural distinctives natively.  DITA uses all normal XML features--don't worry about it being non-standard in this regard. However, the way that DITA exploits some standard W3C features means that you get the best value from editors that recognize those behaviors and support them.

This chart grades editors progressively downward from the ideal:

Levels of DITA compatibility
DITA aware

• Specialization aware (Can match styles to defaulted class attribute values)
• Conref aware (Can render cross-referenced or conrefed content)
• CSS- or XSLT-based (Uses W3C standards for rendering support)

DITA friendly (fails “specialization-aware” but has…)

• CSS-based, and
• Easy to use for topic-length content

XML document friendly (fails W3C standards-based presentation, but has…)

• Proprietary styles
• Book-like or galley orientation

XML data friendly (fails document-like presentation, but has…)

• Everything else that parses, but you wouldn't want to support or use it personally.
  
  

The bar for 2007

So you have an editor in mind that you have qualified as being DITA-aware according to the 2005 level of conformance. What are the marks of editors that are truly competing for distinctiveness this year and onwards?

I believe that the next era began sometime last year, but we are only just now really recognizing that the new challenge for DITA editors will be affordances or usability enhancements keyed to making better use of DITA's features that go beyond usual XML capabilities.  When these are well supported in an editor, it greatly eases the success of the writer working with DITA maps and topics.

Plugging into style:

DITA-enhanced editors striving to meet the 2007 bar should be "DITA aware" as described before--supporting new DITA specializations by associating the new elements to the styling of archetype DTDs and stylesheets. Since DITA processing already supports content interchange between different content owners, regardless of DTD, that same ease of interoperability should exist for the editor as well. If a specialization provides style overrides that enhance the new markup, these should be picked up and applied in the same way that DITA processing applies XSLT deltas to existing transforms.

I'd like to make a modest proposal that editor vendors consider making use of the existing DITA Open Toolkit plugins for specializations. Wouldn't it be great if users could simply point to their existing Toolkit's plugin directory and know that the local editor can likewise find those DTDs and any associated style files for automatic setup?  If you think the plugin definition needs a bit more work, that's fine--bring it up as a requirement. The basic challenge is to install a specialization such as the music plugin into a local Toolkit and have the editor pick up the catalogs, schemas, DTDs, and any provided stylesheets and be able to work immediately with the sample content in those plugins. Bonus points for integrating with whatever processing was also provided with that plugin.  Is that sweet or what?

Make maps the focus of overall operations:

Naturally, the editor should support DITA maps, but not just as Yet Another Doctype.  To make DITA authoring as convenient as possible for writers, the editor should embrace map-creation as the main organizing activity that writers perform in the workspace.  Minimally, the editor should

• Enable authors to easily change the sequence and hierarchy of topicrefs, much like so-called "outliner" chart-making tools.
• Create new stub topics whenever a writer creates a topicref to a not-yet-extant topic.
• Link from the topicref to open up the indicated topic in the topic workspace adjacent to the map.
• Minimally be able to render reltables as literal tables, since the canonical view of reltable tags is rather messy looking (imagine working with CALS table content without an overall table view that hides much of the organizing markup).
• Extra credit for designing the map support so that it can adapt to future specializations, such as bookmap (wherein the map represents book-specific metadata and organization, not just pure hierarchies of topicrefs).

Assist writers with DITA's unique features:

• Quickly identify possible targets for a conref that the writer is creating (akin to finding xref targets, only can apply to any element with an id!).
• Switch between showing original conrefing elements and a verification view that shows the target content as if already replaced (like showing target xref text in the context of the calling xref).
• Treat a ditamap nested tree of topicrefs as an outliner (controls that allow writers to move refs up, down, in, out, or at least drag/drop into new relative locations with ease, rather than cutting/pasting elements within a structure.
• Turn "non-content markup" on or off as needed ("clean" vs "show everything" views). This includes the prolog (which is mostly metadata, no real inline content), index entries, comments, footnotes (which might be rendered alternatively as popovers or endnotes, just as long as they are no longer inline in the "clean" view).
• Show, emphasize, or hide <require-cleanup> and<draft-comment> content as needed.
• Indicate the scope of elements whose selection properties match a given processing profile, so authors can see which elements may or may not be excluded or flagged by conditional processing.
• Support an organization's unique business rules with respect to how writers mark up trademarks, index entries, taxonomy-controlled keywords, and other metadata for the prolog.
• Support external guidelines that inform on good content prepration, such as Accessibility (helping writers check for conforming use of alt text, for example); Translation best practices (available from OASIS and W3C), conref best practices, and so forth.

Help writers bring existing content into DITA:

Migration is not a core requirement of XML or DITA-aware editors. However, the editor is the ideal workspace that offers the kind of tools writers need for doing cleanup on migrated content.  The DITA Open Toolkit offers an HTML to DITA transform, for example, that would be very easy to adapt into the File menu as an Import option, allowing writers to bring HTML content into the editor as rudimentary topics. The import dialog should support both individual files and batch operations (directories, selected files in a group, by a matching pattern, and so forth).

Regardless of the import tool, there is always cleanup to do, so an editor should provide operations to ease the correction of commonly mis-migrated content (moving blocks of content around by drag/drop, or auto-marking content by a persistent pattern (for converting lists or tables into more specific definition lists, for example).

DITA's <required-cleanup> element is an architected way to sequester things that cannot be cleanly mapped in a first validating pass.  Tools should let writers cleanly restore valid structure in this ANY environment and then enable those structures to be moved into desired new locations (or remove the sequestering markup from the now-valid-in-context content).

 

Summary

If you are involved with evaluating editors and other DITA tools, try to have a realistic approach to what you are looking for. Recognize that many of these task-assistive features are only just now appearing on higher-end full XML editors. But you don't have to hold all editors up to these standards.  For example, an emerging class of DITA editors are components that operate through Web browsers, meaning they must trade off full-featured generality for highly focused function in a small footprint.

As I offered back in 2005, ultimately you must make cost/benefit judgments on the features that mean most to your intended scenarios, business rules that need to be supported, and the willingness of your team to learn some new ways of doing things.

 

Related links:

• Evaluating XML editors for DITA--Anne Gentle's blog
• CMS Requirements for DITA--Eliot Kimber's blog
• XML Editors Review--Bob Doyle's column (excellent technical comparison of 12 current editors)
• Migrating to DITA--Kyla Town presentation
• XML and DITA--Bret Freeman translation guidelines
• OASIS DITA TC Translation Subcommittee (currently completing best practices for conref, multi-lingual documents, indexing, and translation memory)