If you just want the slides, they are embedded below via Slideshare.
Free
Tomorrow (February 5) at noon Eastern time, I’m doing a webinar, DITA 101–Why the Buzz?
This is a basic introduction to the Darwin Information Typing Architecture, an XML standard for technical communication content. If you’re wondering about this DITA “thing,” and want to get some basic information, this is the session for you.
Also, the price is right, as it’s free (register here). Audio will be Internet-based, so you don’t even have the expense of a phone call.
Many thanks to MadCap Software, who is organizing and sponsoring this series of free webinars. These sessions are “tool-independent” — they are not going to be pitches for MadCap products.
Cheap
I have to mention Simon Bate’s new Hacking the DITA OT white paper again. It’s crammed with useful tips and tricks on how to get started configuring DITA output to your satisfaction. It’s not free, but at $20 for an instant download, it’s pretty cheap.
Discounted
Conferences are more expensive than our $20 white paper, but they also give you the opportunity to talk with people face-to-face. My next conference event is DocTrain West (Palm Springs, CA). I have two sessions:
You can register for the event at a $400 savings until February 17. I hope to see you there.
by Sheila Loring
Communications from DMN provided a link to a webcast on Essential Tools of an XML Workflow. The webcast focuses on the book publishing industry. It’s interesting to hear that some publishing houses still allow authors and editors to use Microsoft Word. These folks are often viewed as incapable of learning an XML authoring tool. Many times the Word content is sent to an indexer for tagging.
The companies I’ve worked with don’t give their employees the choice of publishing tools, but if you’re Stephen King, you probably won’t be forced to use an XML tool.
Technical writers, if you know how to work with XML, your skills are portable to publishing houses. Don’t overlook this in a job search.
http://toc.oreilly.com/2009/01/webcast-video-essential-tools.html
STC Intercom, January 2009
As the many-to-many communication between blogs, forums, and the like grow in volume, official product information will become just one of the many sources available to readers. Product owners who isolate their official information from the conversation run the risk of not being heard at all.
XML authoring can help to close the documentation gap between official and user-generated content, integrating the two and ensuring their voice is in the mix.
Download the PDF 
(125 K)
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:
Customers tend to adopt non-Open Toolkit solutions when:
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:
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:
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?
Over the years, I have worked on manuals that were translated, and I have helped clients with their localization processes. Despite those experiences, I’ve never been part of a project in which US English was localized (well, localised) into UK English–until now.
Cherryleaf has adapted material from our Technical Writing 101 book in its new Basics of Technical Authoring self-paced course. Cherryleaf is based in the UK, so the course is tailored for those accustomed to British English, but the content is helpful to any English speaker who wants to learn the basics of technical writing. Cherryleaf has also included exercises so students can get some experience applying the techniques explained in the course content.
(Full disclosure: Scriptorium is compensated for sales of Cherryleaf’s course.)
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.
I stumbled upon a list of tips for technical writers, and I was glad to see tip 7:
Understand Your Target Audience. Write and revise your content according to how your target audience thinks and understands things. Getting into their heads–knowing how their minds process information, how they might react, what they feel is important–allows you to customize your content to tailor-fit their needs.
I would put that tip at the top of the list, but that’s a quibble.
Sarah and I mention the topic of audience a lot in our Technical Writing 101 book; I think it is the most important thing for writers to remember as they create content. You can have an elegant XML-based publishing system that generates all sorts of output with the push of a button, but if your information doesn’t address the needs of users, all the work put into the content and into the process itself is wasted.
That waste becomes even more acutely painful when a user abandons your information and finds helpful content on a blog, wiki, or forum. The contributors of that information probably don’t know (or even care) that they followed the Golden Rule of technical documentation: Audience, audience, audience.
A recent post on the dita-users Yahoo group asked how to customize the DITA OT stylesheets in view of the fact that there isn’t much documentation available.
From my work customizing and otherwise perverting the DITA OT, I can sympathize with these frustrations. When I started investigating OT customizations, I found many well-crafted tutorials on how to customize and specialize the OT. These were a great starting point, but they only got me so far. In its current state, the documentation is an incomplete jigsaw puzzle; the trees and buildings are filled in nicely, but the sky is still waiting for someone with patience. (Block that metaphor!)
Because there is no documentation available at the individual template level, you need to reconsider the task at hand. I look on it as debugging, decoding, or sleuthing. With that in mind, I find the following to be very useful:
Probably the best form of documentation that the OT could provide here is additional comments in the stylesheets, particularly about the order of processing. I find I add many comments about where to find the template that handles nodes from an <xsl:apply-templates> directive.
One further note. On Tuesday, September 23, I’ll be presenting the third of our “Best Practices in Structured Authoring and Publishing” joint Webinar series with JustSystems. In this presentation I’ll describe a number of approaches you can use to customize DITA OT output. For more information, visit the JustSystems web site.
Originally published in STC Intercom, April 2008
DITA is a free, pre-made XML document structure. That statement can lead to a few erroneous assumptions: if it’s free, then it will cut down on costs, and if it’s pre-made, it will cut down on labor. There are several things to consider when choosing a DITA solution. Does your staff have the skills to author in a DITA environment? Will additional training be required? Does DITA even match your content model, and if it doesn’t, is it worth the effort to change?
Sarah’s conclusion? “DITA may be free, but it’s not cheap.”
Download the PDF (950 K)
