Skip to main content
Opinion

DITA isn’t magic

The WritePoint staff blog makes a very good point about DITA: it isn’t a magic wand that fixes documentation problems. Also, it’s worth noting that:

… DITA didn’t introduce something completely new. DITA incorporates achievements made in a wide variety of approaches to organizing content that were being proactively conducted starting from 1960’s.

Don’t get me wrong: DITA can be a good solution for many departments that want to set up an XML-based single-sourcing environment. Just don’t expect that a twitch of your nose will convert your legacy content or make the output from the Open Toolkit match your formatting requirements.

Alan Pringle
February 25, 2009
Read More
Tools

Don’t type, drag to the cmd window

I spend a good deal of time with a Windows cmd.exe window open on my desktop. If I’m not running the DITA OT, I’m testing some Perl script, or Ant, or Python, or who knows.

A few years ago (in the Windows 98 days), I discovered a nifty cmd window trick. People are consistently amazed when I demonstrate it to them. Now I’m going to share it with you.

Say you need to change directory to some long and gnarly path name. You could type the whole thing in. Or, if you have Windows Explorer open on your desktop, you can:

  1. Type “cd ” in the cmd window (the space is important).
  2. Go to Windows Explorer and find the folder you want to navigate to.
  3. Drag and drop the folder from Windows Explorer to the cmd window.

Hey presto! The path name is copied to the cmd window. What’s more, if there are spaces in the path, the path is automatically quoted.

Now you can click in the cmd window and press Enter to perform the command.

Cool! No more typing long path names for this ToolSmith.

This works for filenames too. If I’m running a Perl script that needs to work on a file way down my directory tree, I type “perl myScriptName.pl “, then drag and drop the file name from Windows Explorer into my cmd window.

I’ll keep adding more ToolSmith’s Tricks as I use them. What’s your favorite trick?

Simon Bate
February 20, 2009
Read More
Tools

WMF…that’ll shut ’em up

Which graphics formats should you use in your documentation? For print, the traditional advice is EPS for line drawings and TIFF for screen captures and photographs. That’s still good advice. These days, you might choose PDF and PNG for the same purposes. There are caveats for each of these formats, but in general, these are excellent choices.

Of course, everybody knows to stay away from WMF, the Windows Metafile Format. WMF doesn’t handle gradients, can’t have more than 256 colors, and refuses to play nice with anything other than Windows.

Think you’re too good to hang out with WMF? For your print and online documentation, perhaps. But it may be a great choice to give to your company’s PowerPoint users.

Are you familiar with this scenario? PowerPoint User saw some graphics in your documentation and thought they would work for some sales presentations. The screen captures are easy; you just give PowerPoint User PNGs or BMPs or whatever. It’s the line drawings that are the problem. PowerPoint User doesn’t have Illustrator and has never heard of EPS. PowerPoint User says, “Can you give me a copy of those pictures in a format that I can use in PowerPoint? Oh, and can make that box purple and change that font for me first? And move that line just a little bit? And make that line thicker? And remove that entire right side of the picture and split it into two pictures?”

You want PowerPoint User to reuse the graphics; you’re all about reuse. But you have dealt with PowerPoint User before, and you know you will never get your real job done if you get pulled into the sucking vortex of PowerPoint User’s endless requests.

The secret is to give PowerPoint User the graphics in a format that can be edited from within PowerPoint (or Word): WMF. Here’s the drill that will make you a hero:

  1. Save your graphics as WMF.
  2. Place each WMF on a separate page in a PowerPoint or Word file.
  3. Tell PowerPoint User to double-click on a graphic to make it editable.(If you think your PowerPoint User is really dumb, you can double-click the graphic and respond to the dialog box asking if you want to make the drawing editable yourself before saving the file, but nobody is that dumb.)

WMF. It will make PowerPoint User go away…happy!

Sarah O'Keefe
February 20, 2009
Read More
Reviews

Review of screen capture programs

by Sheila Loring

Matthew Ellison reviews seven screen capture programs: FullShot, HyperSnap, SnagIt, Madcap Capture, RoboScreen Capture, ScreenHunter (free), and TNT. He also points out what to look for in a screen capture tool and compares features in a handy table.

http://www.writersua.com/articles/capturetools/index.html

SnagIt lands at the top of the bunch. Matthew describes it as “the most full-featured of the capture tools reviewed in this article.”

I’m a recent SnagIt convert after using Paint Shop Pro for years. SnagIt can’t be beat for a quick, easy screen shot. I also like the torn edge options to indicate a partial shot of the GUI. But the jagged edges might be more of a creative device than helpful visual cue. What do you think?


ScriptoriumTech
February 17, 2009
Read More
Conferences

Upcoming DITA events (free, cheap, and discounted)

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:

  • What Gutenberg Can Teach Us about XML: This session looks at movable type and explores how the changes introduced by the printing press compare to the changes introduced by XML.
  • Demystifying DITA to PDF Publishing: This session discusses the advantages and disadvantages of each approach to extracting PDF from DITA content. Includes discussion of the DITA Open Toolkit, FrameMaker, and InDesign.

You can register for the event at a $400 savings until February 17. I hope to see you there.

Sarah O'Keefe
February 4, 2009
Read More
Webinar

Essential tools of an XML workflow in the publishing industry

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

ScriptoriumTech
February 2, 2009
Read More
Content strategy XML

Web 2.0: The tipping point for XML

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 PDF file (125 K)

Sarah O'Keefe
January 31, 2009
Read More
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
Localization

We’ve been localised

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.)

Alan Pringle
November 21, 2008
Read More