At this month’s meeting, Don Day discussed “More than just another XML editor” to help us all with editor evaluations that are specific to DITA support. Our summer series of topics have been centered around tools, and next month a Quadralay rep will present “something cool.” Quadralay, the folks who bring us WebWorks, is here in Austin so we’re lucky to have some vendors in the neighborhood.
Evaluating DITA editors
Don talked us through an editor evaluation from start to finish. When they’re available, I’ll link to Don’s slides, but I’ll also do a notes dump here. These notes are my thoughts, and not a summary of Don’s presentation.
He stepped us through the classes of editors and also worked his way up to what types of use cases the enterprise users are looking for. I found the use cases very helpful. Yes, there are DITA specific features to keep in mind as well. But the installation and configuration, customization for writers, suitability for your company’s strategic format, usability, and productivity gains are the right considerations. It’s also good to hear from someone who has been working in an XML editor for a while and can tell you what to look for next, once you satisfy your first few rounds of requirements (for example, the editor has to validate XML, that’s definitely a first round requirement.)
After validation, what sets an XML editor apart? For me, on the next level is the entities support. For DITA, this support is all about how usable the conref feature is for reusing parts of content. As an example, if you want your writers to use a standard list of product names, you can use conref to bring in only the correct names from the master list. (Think of Framemaker variables).
The next level is the resource manager, how well does it handle graphics and links to external documents? Let’s definitely not make that a pain when it’s straightforward in other writing tools.
After that, consider which views your writers can see – structured, tags on or off, and try to anticipate what your writers will want in the views. For me, that’s not easy, because every writer will want a different view, but customization is definitely a needed feature. Does it have pre- and partial-rendering views (or would you rather it didn’t to help train writers to get away from output and format and focus on content?)
Additional pluses include native (or plugin) viewing of notation or namespaced data, such as SVG graphics. For hardware companies I would imagine this is a must have. For software companies, I’m still investigating how important this feature is – I imagine it’s not a deal breaker for us.
The next plus he named was the suitability of user interface features to user assistance content authoring. My guess is that this is a huge one for most writers – does the editor feel like an author’s tool or a programmer’s tool? Now, interestingly, while I was drafting this post, I read The Content Wrangler’s great summation of his recent interviews with people doing DITA implementations. It’s a top ten list — 10 DITA Lessons Learned From Tech Writers in the Trenches. My favorite gems are from number 9: Don’t Fall In Love With Software.
- Far too many technical writers fall hopelessly in love with an authoring tool for no apparent business reason.
- Software love affairs are good for vendors because they convert regular, ordinary writers into mindless, unpaid software evangelists.
- Love affairs of this sort are bad for organizations that employ technical writers because they prevent us from asking questions about our own choices, our own motivations, and the impact our personal preferences may have on the organizations for which we work. Love is an emotional thing, while business is about return on investment, profit and longevity.
This is a great post, one that I will read and re-read and tell others to read as we go through more planning for our structured authoring projects.
One item that Don mentioned that I hadn’t though of before this talk are whether the editor supports macros. (However, I also think that macro support might fly in the face of the previous “author’s tool or programmer’s tool” question.) His example macro was of a cut and paste across multiple docs with a save at the end, saving the writer a lot of time by using a simple recorded macro.
Another good consideration is the viability of the company that makes the editor you like. Will service and support be around in the years to come? That’s always a good question to investigate while testing out software to purchase.
Does the editor match your processing framework (or be made to do so?) On an enterprise level this is really important. It has to be able to get the docs in front of customers in a sensible manner without a lot of intervention (in my perfect world).
Typical authoring scenarios
Now, to me, these are authoring scenarios straight out of IBM, so your company may have different scenarios in mind. I have a few more I might add as well that I’ll be evaluating.
- Start a new topic. This one is huge for people who are accustomed to the ease of templates. How about starting a new Map though? We’re one of the few companies I’ve heard of specializing map files so that writers just have map templates that they’d fill in with specific topics. We might back off that idea as it causes a lot of specialization work, but it’s a scenario I’d like to try out.
- Clean up a topic newly migrated. This one is definitely a biggie with thousands of migrated topics, youch. But, if you only plan to write new content as topics, this scenario might not be a high priority
- Revise existing already validated content. Yes, this scenario can make or break an editor’s ease of use. How difficult is it to pick through to discover where you broke your perfectly valid document (and how much flex does the editor give you while you try to organize your structure and sentences?)
- Create conrefs and links. I think of writing a glossary using conrefs to a giant master glossary and just picking and choosing the terms that matter for your particular deliverable.
- Authoring metadata, then hiding metadata that you don’t want to read in the topic as you author. I think of the prolog in a topic with things like authors and versions, info that might get in the way of readability as you author.
- Inline alternative content in place and the ability to hide it. I think of index entries cluttering up your nice content while you author.
- Pre-rendered views and partially rendered views With this scenario, I think of whether you want to be able to view Headings in a certain font or size, and viewing other formatting renditions.
Let’s talk about DITA-friendly features
Awareness of DITA’s approach to topics, such as specialization awareness, conref awareness, and Don especially feels that CSS styling and XSLT styling, both W3c standards, are a high priority for DITA friendliness. Easy to use for topic-length content and documentation is another DITA-friendly item. Specifically for CSS, a nicety is substring matches on class attributes. Proprietary styling isn’t exactly in the best interest of a DITA effort where part or most of the goal is re-use (not just of your topics but of the processes to make the topics).
Another consideration (from the audience, I believe) is how well will the tool pick up on new releases of the DITA Open Toolkit? A responsive vendor will be well aware of us chomping at the bit for the newest releases especially for new specializations and stylesheets or transforms.
Imparted final wisdom
The business benefits of DITA are at the heart of the matter. Think of how your business plans to use DITA to help your deliverables shine… will you require new specialization to do so and therefore want a lot of design features? Or will you stick to the core info types (concept, task, and reference), and therefore move your primary criterion to customization or maintenance? As Don says, these guides will help you select top candidates, but may not reduce the selection to one very quickly, so you must represent your business’s value system in the final decision. Now, that said, his last question on his Heuristic Evaluation is “Will your writers use it?” That’s a big question to keep in mind!
I’d love to hear your thoughts on what editor evaluations you’ve done – not necessarily a discussion on “this editor is the best” but more about what scenarios we should test, and why, especially from a business case perspective.