Skip to main content

Tag: dita

Opinion

Publishing DITA without the DITA Open Toolkit: A Trend or a Temporary Detour?

I estimate that about 80 percent of our consulting work is XML implementation. And about 80 percent of our XML implementation work is based on DITA. So we spend a lot of time with DITA and the DITA Open Toolkit.

I’m starting to wonder, though, whether the adoption rate of DITA and the DITA Open Toolkit is going to diverge.

For DITA, what we hear most often is that it’s “good enough.” DITA may not be a perfect fit for a customer’s content, but our customer doesn’t see a compelling reason to build the perfect structure. In other words, they are willing to compromise on document structure. DITA structure, even without specialization, offers a reasonable topic-based solution.

But for output, the requirements tend to be much more exacting. Customers want any output to match their established look and feel requirements precisely.

Widespread adoption of DITA leads to a a sort of herd effect with safety in numbers. Not so for the Open Toolkit — output requirements vary widely and people are reluctant to contribute back to the Open Toolkit, perhaps because look and feel is considered proprietary.

The pattern we’re seeing is that customers adopt the Open Toolkit when:

  • They intend to deploy onto multiple servers, and open source avoids licensing headaches.
  • The Open Toolkit provides a useful starting point for their output format.

Customers tend to adopt non-Open Toolkit solutions when:

  • They need attractive PDF. Getting this result from the Open Toolkit isn’t quite impossible, but it’s hard. There are other options that are faster, cheaper, and easier.
  • They need a format that the Open Toolkit doesn’t provide. The most common requirement here is web-based help. Getting from the XHTML output in the Open Toolkit over to a sophisticated tri-pane help system with table of contents, index, and search….well, let’s just say that it keeps me gainfully employed. AIR is another platform that we need to support.

The software vendors seem to be encouraging this trend. In part, I think they would like to find some way to get lock-in on DITA content. Consider the following:

  • Adobe FrameMaker can output lovely PDF from DITA content through FrameMaker (no Open Toolkit). You can also use the Open Toolkit to generate formats such as HTML.
  • ePublisher Pro uses the Open Toolkit under the covers, but provides a GUI that attempts to hide the complexities.
  • MadCap’s software will support DITA (initially) by importing DITA content and letting you publish through MadCap’s existing publishing engine.
  • Several other vendors provide support for publishing DITA, but do not use the Open Toolkit at all.

The strategy of supporting DITA structure through a proprietary publishing engine actually makes a lot of sense to me. From a customer point of view, you can:

  • Set up an XML-based authoring workflow
  • Manage XML content

It’s not until you’re ready to publish that you move into a proprietary environment.

To me, the interesting question is this: Will the use of proprietary publishing engines be a temporary phenomenon, or will the Open Toolkit eventually displace them in the same way that DITA is displacing custom XML structure?

Sarah O'Keefe
December 1, 2008
Read More
Conferences

Looking Fear Straight in the Eye

Have you ever been really scared? I don’t mean just the Halloween kinda scared, but really scared. That’s how I felt at the Burlington Marriott when the hotel employee delivered the box containing the workbooks for my Introduction to XMetaL and DITA workshop. He stood in the doorway, smiled, and handed me a very beat up, bent, folded, spindled, and mutilated FedEx box.

The box looked like the driver had had a flat on Route 128 and used it to prevent the truck from rolling back while jacking up the front end. It was nice and damp too. With much trepidation, I opened the box and — to my relief — found that the materials were undamaged. Whew.

Following that, Wednesday’s all-day workshop on XMetaL and DITA was smooth sailing. OK, we had a bit of a problem with powerstrips, but the helpful DocTrain folks got that taken care of. In retrospect, many of the questions I fielded in the workshop weren’t so much about DITA or XMetaL itself. Instead many of the questions were about generating output. The fact is that unless you’re willing to spend some quality time with CSS and the DITA Open Toolkit, your output from DITA will look very generic. XMetaL has a number of hooks that ease some of the pain in generating XHTML output. But even those hooks won’t save you from FO issues if you want to generate PDF output.

In my presentation on Thursday comparing XMetaL and FrameMaker support in DITA, the questions returned once again to output. Of course, this time the focus was on using FrameMaker 8.0 as a PDF engine. In workflows where content is created and maintained in XML, but then has to be delivered in PDF (or print), FrameMaker 8.0 looks like an attractive possibility. There are a few flaws in this solution (such as translating xref elements for intra-document links into live links in PDF), but users are closer to a solution than they were six months ago.

We’ve posted PDFs of the slides from both sessions on SlideShare.

You can find the Introduction to XMetaL and DITA workshop slides at:

http://www.slideshare.net/Scriptorium/xmetal-dita-workshop-presentation

The slides for the session on DITA Support in FrameMaker and XMetaL are at:

http://www.slideshare.net/Scriptorium/dita-support-in-framemaker-and-xmetal-presentation

When you’re done browsing the slides, take a look on our site for information about how we can help you with your FrameMaker, XMetaL, OT, PDF problems.

It’s not that scary.

Simon Bate
November 3, 2008
Read More
Conferences

WritersUA: DITA pilot techniques

Mark Wallis of IBM ISS on how to run a successful DITA pilot. Some great information in this presentation on how to reduce risks.

He recommends selecting your pilot project based on the following items:

  • Right timeframe — don’t choose the project that has an imminent release
  • Choose a manageable documentation set size
  • Reduce risk by avoiding the strongest (or most critical) product
  • Identify a product with a known need to improve the user experience

They had one person out of a group of twelve, a “senior in name only” writer, leave because of this transition.

The ideal team for a pilot will need cross-functional and complementary skills:

  • Project management skills
  • Tools and technology strengths
  • Product knowledge and understanding
  • Architecture and design skills
  • Editor for standards and styles

Some advice on planning your content. (And it’s worth noting here that these apply to good writing and topic-oriented content rather than to DITA tools.)

  • No autopilot writing
  • Don’t just migrate existing content; you’ll get trapped in old paradigms (this assumes that existing content does not fit the DITA topic paradigm)
  • Perform use case analysis and task analysis
  • Determine the critical scenarios to document
  • Focus on tasks; backfill supporting information as needed

Some interesting discussion of “task support clusters,” which include conceptual overviews, related tasks, deep concept, and reference information. (Michael Hughes did a presentation on this earlier today, which I unfortunately was not able to attend.)

They set up a DITA War Room in a small conference room and met at least daily (1.5 to 2 hours per day. Yikes). They set weekly goals and used small tasks to build momentum.

There was also heavy use of an internal wiki to put up initial “straw man” design, then revise, comment, and discuss.

Layering deliverables
Implementation deliverables were split out into smaller tasks, such as:

  • Creating topic files, links, and navigation
  • Testing links from code and navigation
  • Creating task and reference topics
  • Validating help against the user interface
  • Creating concept topics for principles, guidelines, and best practices (“deep concept”)
  • Validating content in the expert community

For the third time, he points out that they are no longer documenting how to use a check box, so I guess I’ll mention it.

Choosing the DITA toolset

Task Modeler (free) for building and managing ditamaps, defining relationships between topics, and creating skeleton topics (stub files).

DITA-compliant editor to edit your topics.

Compiler (part of open source toolkit). Compiler? What are they compiling? HTML Help? Oh. He just referred to Ant as a compiler. Ohhhhhkay.

Proof of concept

They picked a subset of the pilot to do the proof of concept.

The presenter’s boss is quoted as saying, “There’s no such thing as bad weather, only insufficient clothing.” I’m guessing that she’s never been to Minnesota in winter.

The objectives for the proof of concept:

  • Learn and evaluate tools
  • Address technical obstacles
  • Specify end-to-end requirements

They learned that deliverable formats matter because they must deliver several different formats.

Managing costs

Purchase toolsets only for pilot team.

After completing proof of concept (successfully!), invest in tools for the remaining writers.

Wiki

They used their wiki to capture conventions and guidelines.

Improving acceptance

They paid attention to the change management issues. He doesn’t mention it here, but I would assume that the combination of an acquisition by IBM plus the requirement to change the authoring environment could have caused significant angst. Their approach included presentations, wiki content, email discussions, and online training.

At the point of transition, DITA boot camp was offered.

They used collaborative walkthroughs, or reviews, to help standardize their content development. Interesting. This sounds as though it could be a) threatening and b) an unbelievable time sink. But just maybe it might also c) help improve the content.

Other lessons learned

Think more, write less. (Don’t document the obvious, don’t document common user interface convention, write only if you’re really adding value.)

Don’t squander your ignorance. (If something makes you stumble in the interface, that will probably also cause problems for your users, so capture it.)

The more structured your content, the easier the transition to DITA.

Documenting the obvious teaches readers to ignore your text, so don’t document the obvious.

The handouts are available here: http://www.writersua.com/ohc/suppmatl/

Sarah O'Keefe
March 19, 2008
Read More
Opinion

Why XML and structured authoring is a tough transition

Found on technicalwriter’s blog:

There are several applications that incorporate features for DITA use, such as XMetal and Altova Authentic, but how much value do they provide? (Looking over the online documentation for XMetal, you will see some pretty shaky formatting and copyfitting.)

There may well be formatting and copyfitting issues. Wouldn’t surprise me at all. But talk about missing the forest for the trees!

DITA/XML/structured authoring are important because they improve how information is stored. To question their value because somebody produced documentation using them that doesn’t look so great…let’s try an analogy:

Last week, I went to a restaurant and the food was terrible. I looked in the kitchen and saw Calphalon pots and pans. I conclude that you should not buy Calphalon because the food they produce is terrible.

The quality of your food is determined by things such as the quality of the ingredients and the skill of the chef. The pan you choose does contribute — it helps to use the right size and a high-quality pan, but to dismiss DITA because one example doesn’t look quite right is pretty much like dismissing Calphalon because somebody once cooked something that didn’t taste very good in it.

PS I like Calphalon. And I have produced my share of problematic entrees.
PPS DITA is not right for everybody.

Sarah O'Keefe
May 4, 2007
Read More