Random thoughts about publishing

Site Feed

Labels

Palimpsest has moved. Please visit our blog in its new location for the most recent posts from Scriptorium.

Palimpsest

 

Learn DITA and XML at your desk

Monday, August 10, 2009 — posted by Sarah O'Keefe

Labels: dita, DITA Open Toolkit, PDF, webcasts, xml

9:02 AM Permalink | |

 

Flare 5 DITA feature review, part 2

Wednesday, June 17, 2009 — posted by Sarah O'Keefe

[Alan Pringle wrote most of this review.]

This post is Part 2 of our Flare 5 DITA feature review. Part 1 provides an overview and discusses localization and map files.

Cross-references and other links
I imported DITA content that contained three xref elements (I shortened the IDs below for readability):

• Reference to another step in the same topic:
  <stepresult>
  Result of step. And here's a reference to the <xref href="task1.xml#task_8F2F9" type="li" format="dita" scope="local">third step</xref>.
  </stepresult>
  

• Reference to another topic:
  <stepresult>
  Result text. And here's a link to the other task topic:
  <xref href="task2.xml#task_8F2F94 type="task" format="dita" scope="local"></xref>.
  </stepresult>
  

• Link to web site:
  <cmd>
  Here's another step. Here's a link with external scope:
  <xref href="http://www.scriptorium.com" scope="external" format="html">www.scriptorium.com</xref>
  </cmd>
  

All three came across in the WebHelp I generated from Flare:


On the link to the topic, Flare applied a default cross-reference format that included the word "See" and the quotation marks around the topic's name. You can modify the stylesheet for the Flare project to change that text and styling.

Relationship tables
DITA relationship tables let you avoid the drudgery of manually inserting (and managing!) related topic links. Based on the relationships you specify in the table, related topic links are generated in your output.

I imported a simple map file with a relationship table into Flare and created WebHelp. The output included the links to the related topics. I then tinkered with the project's stylesheet and its language skin for English to change the default appearance and text of the heading for related concepts. The sentence-style capitalization and red text for "Related concepts" in the following screen shot reflect my modifications:


conrefs
DITA conrefs let you reuse chunks of content. I created a simple conref for a note and then imported the map file with one DITA file that contains the actual note and a second file that references the note via a conref.

Flare happily imported the information and turned the conref into a Flare snippet. It's worth noting that the referencing, while equivalent, is not the same. In my source DITA files, I had this:

aardvark.xml contains:
<note id="">Do not feed the animals

baboon.xml contains:
<note conref="aardvark.xml#aardvark/nofeeding">

Thus, we have two instances of the content in the DITA files -- the original content and the content reference. In Flare, we end up with three instances -- the snippet and two references to the snippet. In other words, Flare separates out the content being reused into a snippet and then references the snippet. This isn't necessarily a bad thing, but it's worth noting.

Specialization
Specialized content is not officially supported at this point. According to MadCap, it worked for some people in testing, but not for others. If you need to publish specialized DITA content through Flare, you might consider generalizing back to standard DITA first.

Conditional processing
When you import DITA content that contains attribute values, Flare creates condition tags based on those values. I imported a map file with a topic that used the audience attribute: one paragraph had that attribute set to user, and another had the attribute set to admin. When I looked in the Project Organizer at the conditions for the WebHelp target, conditions based on my audience values were listed:

I set Audience.admin to Exclude and Audience.user to Include, and then I created WebHelp. As expected, the output included the user-level paragraph and excluded the admin-level one.

DITA support level
Flare supports DITA v1.1.


Our verdict

If you're looking for a path to browser-based help for your DITA content, you should consider the new version of Flare. Without a lot of effort, we were able to create WebHelp from imported DITA content. Flare handled DITA constructs (such as conrefs and relationship tables) without any problems in our testing. Our only quibble was with the TOC entries in the WebHelp (as mentioned in Part 1), and we've heard that MadCap will likely be addressing that issue in the future.

We didn't evaluate how Flare handles DITA-to-PDF conversion. However, if the PDF process in Flare works as smoothly as the one for WebHelp, Flare could provide a compelling alternative to modifying the XSL-FO templates that come with the Open Toolkit or adopting one of the commercial FO solutions for rendering PDF output.

Labels: dita, flare, reviews

2:00 PM Permalink | |

 

Flare 5 DITA feature review (Part 1: Overview and map files)

Friday, June 12, 2009 — posted by Sarah O'Keefe

[Disclosure: Scriptorium is a Certified Flare Instructor.]
[Full disclosure: We're also an Adobe Authorized Training Center, a JustSystems Services Partner, a founding member of TechComm Alliance, a North Carolina corporation, and a woman-owned business. Dog people outnumber cat people in our office. Can I start my post now?]

These days, most of our work uses XML and/or DITA as foundational technologies. As a result, our interest in help authoring tools such as Flare and RoboHelp has been muted. However, with the release of Flare 5, MadCap has added support for DITA. This review looks at the DITA features in the new product. (If you're looking for a discussion of all the new features, I suggest you wander over to Paul Pehrson's review. You might also read the official MadCap press release.)

The initial coverage reminds me a bit of this:



(My web site stats prove that you people are suckers for video. Also, I highly recommend TubeChop for extracting a portion of a YouTube video.)

Let's take a look at the most important Flare/DITA integration pieces.

New output possibilities
After importing DITA content into Flare, you can publish to any of the output formats that Flare supports. Most important, in my opinion, is the option to publish cross-browser, cross-platform HTML-based help ("web help") because the DITA Open Toolkit does not provide this output. We have created web help systems by customizing the Open Toolkit output, and that approach does make sense in certain situations, but the option to publish through Flare is appealing for several reasons:

• Flare provides a default template for web help output (actually, three of them: WebHelp, WebHelp Plus, and WebHelp AIR)
  
• Customizing Flare output is easier than configuring the Open Toolkit
  

I took some DITA files, opened them in Flare, made some minimal formatting changes, and published to WebHelp. The result is shown here:

Not bad at all for 10 minutes' work. I added the owl logo and scriptorium.com in the header, changed the default font to sans-serif, and made the heading purple. Tweaking CSS in Flare's visual editor is straightforward, and changes automatically cascade (sorry) across all the project files.

Ease of configuration
Flare wins. Next topic. (Don't believe me? Read the DITA Open Toolkit User Guide -- actually, just skim the table of contents.)

Language support
The Open Toolkit wins on volume and for right-to-left languages; Flare wins on easy configuration (I'm detecting a theme here.)

Out of the box, both Flare and the Open Toolkit provide strings (that is, localized output for interface elements such as the "Table of Contents" label) for simplified and traditional Chinese, Danish, Dutch, English, Finnish, French, German, Italian, Japanese, Korean, Norwegian, Portugese, Spanish, Swedish, and Thai (I have omitted variations such as Canadian French).

Beyond that, we have the following:

• Right-to-left language support: Only in the Open Toolkit
• Language strings provided by the Open Toolkit but not by Flare: Arabic, Belarusian, Bulgarian, Catalan, Czech, Greek, Estonian, Hebrew, Croatian, Hungarian, Icelandic, Latvian, Lithuanian, Macedonian, Polish, Romanian, Russian, Slovak, Slovenian, Serbian, Turkish, and Ukrainian
• Ease of adding support for a new language: Flare wins. In the Open Toolkit, you modify an XML file; in Flare, you use the Language Skin Editor (although it looks as though you could choose to modify the resource file directory directly if you really wanted to)
  

Thus, if you need Hebrew or Arabic publishing, you can't use Flare. The Open Toolkit also provides default support for more languages.

Map files
I imported a map file into Flare and published. Then, I changed the map file to include a simple nested ditamap. Here is what I found:

• Flare recognized the map file and the nested map file and built TOC files in Flare with the correct relationships.
• Inexplicably, the nested map file was designated the primary TOC. I speculate that this might be because the nested map file was first in alphabetical order. I changed the parent map file to be the primary TOC to fix this. I don't know what would happen for a more complex set of maps, but I am concerned.
• Flare inserted an extra layer into the output TOC where the nested map is found.
• The titles generated in the TOC are different in Flare than they are through the DITA Open Toolkit (see below).
  

I generated the output for my map file (the nested map is the "The decision to implement" section in this screen shot) through the DITA Open Toolkit and got the following XHTML output:
Then, I imported the same map file into Flare, generated WebHelp, and got the following TOC output:

Notice that:

• The TOC text is different (!!). The DITA Open Toolkit uses the text of the topic titles from inside the topic files. Flare uses the text of the @navtitle attribute in the map file. My topic titles and @navtitles don't match because I created the map file, then changed a bunch of topic titles. The map file didn't keep up with the new titles (because it doesn't matter in the Open Toolkit), but it appears to matter for Flare. The entry in the map file for the first item is:

<topicref href="introduction.xml" navtitle="Introduction" type="topic">

Flare picks up the "Introduction" from the navtitle attribute.

Inside the file, you find:


<title>Executive summary</title>

The Open Toolkit uses the content of the title element from inside the file.


• The Implementation section has added an extra layer in the Flare output. It appears that nesting a map file results in an extra level of hierarchy.

The inconsistency between the two implementations is annoying.

In part 2 of this review (coming soon), I'll look at cross-references, reltables, conrefs, specialization, and conditional processing.

Labels: analysis, dita, DITA Open Toolkit, flare, reviews

10:05 AM Permalink | |

 

DocTrain's demise and a challenge to presenters

Monday, May 18, 2009 — posted by Sarah O'Keefe

Unfortunate news in my inbox this morning:

I regret to announce that DocTrain DITA Indianapolis is cancelled. DocTrain/PUBSNET Inc is shutting down.

As a business owner, messages like this strike fear in my heart. If it could happen to them...gulp. (This might be a good time to mention that we are ALWAYS looking for projects, so send them on over, please.) My condolences to the principals at DocTrain.

Meanwhile, I'm also thinking about what we can do in place of the event. I had a couple of presentations scheduled for DocTrain DITA, and Simon Bate was planning a day-long workshop on DITA Open Toolkit configuration.

So, here's the plan. We are going to offer a couple of webinars based on the sessions we were planning to do at DocTrain DITA:

• Demystifying DITA to PDF Publishing, June 2, 11 a.m. Eastern time (Sarah O'Keefe)
  
• Hacking the DITA Open Toolkit, June 4, 11 a.m. Eastern time (Simon Bate)

Each webinar is $20. We may record the webinars and make the recordings available later, but I'm not making any promises. Registration is limited to 50 people.

Here's the challenge part: If you were scheduled to present at DocTrain DITA (or weren't but have something useful to say), please set up a webcast of your presentation. It would be ultra-cool if we could replicate the event online (I know that the first week in June was cleared on your schedule!), but let's get as much of this content as possible available. If you do not have a way to offer a webinar, let me know, and I'll work with you to host it through Scriptorium.

And here's my challenge to those of you who like to attend conferences: Please consider supporting these online events. If $20 is truly more than you can afford, contact me.

Labels: dita, DITA Open Toolkit, doctrain, PDF, presentations

4:13 PM Permalink | |

 

Structured authoring in technical communication

Monday, April 27, 2009 — posted by Sarah O'Keefe

I am pleased to announce the publication of our newest white paper, The State of Structured Authoring in Technical Communication. In early 2009, we conducted a survey on structured authoring; this document presents the results of the survey along with our analysis.

Those who participated in the survey are entitled to a free copy of the report. If you requested a copy via email, you will receive a message within the next 2 business days with download instructions. If you requested a printed copy, those will go in the mail tomorrow.

The report is also available for purchase and immediate download. The cost is $200 for the 38-page report (plus 18 pages that reproduce the survey questions, so the file is 56 pages long).

I'm also delivering a presentation at next week's STC Summit in Atlanta, which discusses the results of the survey. If you're attending the conference, I hope you'll join me on Monday, May 5, from 1:30 to 2:30 p.m. in Regency V for "The State of Structure."

Labels: analysis, change management, dita, structured authoring, survey, white papers

5:00 PM Permalink | |

 

DITA adoption increasing overall structured authoring adoption

Monday, March 30, 2009 — posted by Sarah O'Keefe

I'm knee-deep in survey data analysis. With over 600 responses, our recent structured authoring survey was hugely successful--thank you. Many respondents added candid details about their experiences with structured authoring implementation--their fears, mistakes, and biggest surprises.

The survey report will be available later this month (free to participants, $200 for others), but I wanted to give you a couple of preliminary highlights:

• About 30 percent of respondents said that they are currently using structured authoring.
• There's a lot of hype around DITA, but our data indicates that it's backed up by reality. Consider this chart, which shows the top three types of structure (custom, DocBook, or DITA) implemented, being implemented, or planned.

DITA dominates the chart. But it looks as though DITA is additive. That is, it's not cannibalizing the numbers for DocBook or custom structures. Those numbers are relatively flat. Instead, it looks as though DITA is increasing the total number of implementations.

If you are attending the STC Summit this year, I'm doing a presentation on the survey results on Monday, May 4, at 1:30 p.m., called "The State of Structure."

Labels: analysis, dita, survey

10:37 PM Permalink | |

 

Life in the desert

Monday, March 23, 2009 — posted by Sarah O'Keefe

Last week, I attended the annual DocTrain West event, which was held this year in Palm Springs, California.

Weather in Palm Springs was spectacular as always with highs in the 80s during the day. Some of my more northerly friends seemed a bit shell-shocked by the sudden change from snow and slush to sun and sand. (North Carolina was 40 degrees when I left, so that was a nice change for me as well.)

Scott Abel did his usual fine job of organizing and somehow being omnipresent.

I promised to post my session slides. The closing keynote was mostly images and is probably not that useful without audio, so I'm going to point you to an article that covers similar ground (What do Movable Type and XML Have in Common, PDF link).

I have embedded the slides from my DITA to PDF session below.

I have also posted the InDesign template file and the XSL we built to preprocess the DITA XML into something that InDesign likes on our wiki. Note that running the XSL requires a working configuration of the DITA Open Toolkit. For more information, refer to the DITA to InDesign page on our wiki.

Labels: conferences, dita, doctrain, InDesign

2:51 PM Permalink | |

 

DITA isn't magic

Wednesday, February 25, 2009 — posted by Alan Pringle

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.

Labels: dita, structured authoring

8:02 AM Permalink | |

 

DITA webinar now available...

Tuesday, February 10, 2009 — posted by Sarah O'Keefe

Labels: dita, presentations, xml

10:48 AM Permalink | |

 

Upcoming DITA events (free, cheap, and discounted)

Wednesday, February 04, 2009 — posted by Sarah O'Keefe

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.

Labels: conferences, dita

2:26 PM Permalink | |

 

DITAlini and Chickpeas

Friday, January 09, 2009 — posted by Simon Bate

2 Tbsp olive oil
1-2 cloves garlic, minced
2 15 oz. cans chickpeas (NOT drained)
1 14 oz. can diced tomatoes, drained
1/2 tsp each thyme, rosemary, oregano, basil, marjoram
1 tsp salt
1/4 tsp pepper
1 cup ditalini (uncooked)

Heat the oil in a 3-4 quart saucepan. Add the garlic and allow to brown slightly.

Add the peas and their liquid, the tomatoes, pasta, salt and pepper, and ditalini. Bring to a boil, then let simmer for 15 minutes, stirring occasionally. Season to taste and serve.

Grate some Parmigiano-Reggiano over each serving.

Labels: dita, ditalini, potluck, recipes

1:31 PM Permalink | |

 

Fixing FOP memory errors

Wednesday, December 17, 2008 — posted by Sarah O'Keefe

Our newest white paper describes how to process large documents with XSL-FO and avoid memory errors. Here's the introduction:

Formatting Object (FO) processors (FOP, in particular) often fail with memory errors when processing very large documents for PDF output. Typically in XSL:FO, the body of a document is contained in a single fo:page-sequence element. When FO documents are converted to PDF output, the FO processor holds an entire fo:page-sequence in memory to perform pagination adjustments over the span of the sequence. Very large page counts can result in memory overflows or Java heap space errors. Reducing page count in a document is not usually an option.

The full white paper is Handling XSL-FO's memory issue with large page counts. Many thanks to David Kelly (writing), Simon Bate (reviewing), Alan Pringle (editing), and Ethan Duty (productioning, er, production).

As always, we welcome your comments here or directly in the white paper pages. If you have ideas for topics you'd like us to cover, we're all ears.

Labels: dita, DITA Open Toolkit, white papers, xsl-fo

10:12 PM Permalink | |

 

Put the drawing tools down!

Thursday, December 11, 2008 — posted by Alan Pringle

This list of technical writing myths has a decidedly DITA slant; I don't necessarily like the idea of DITA driving what is and isn't acceptable practice for technical writing. That being said, I endorse the information provided about myth #4:

4. The Callouts on Graphics Myth

If you want to reuse the same graphic in multiple publications and even multiple languages, it is a good practice not to put callouts in the source file of the graphic itself. Instead, you place your callouts "on top of" your graphic in your text editor (Word) or DTP program (InDesign, FrameMaker, ...). This is not supported in DITA. Therefore, if you need to use callouts in graphics, try to use language-independent ones (A, B, C...) in the source file of the graphic and put the explanation of these callouts in a table below the graphic in your DITA XML content. [Yves Barbion]

It's not just the DITA standard that doesn't support callouts placed with a document processor's drawing tools. We have a client for whom we created a custom XML structure for FrameMaker content, and that content contains many graphics with callouts. The client translates the content into multiple languages.

In the previous workflow in unstructured FrameMaker, the client placed the callouts in the anchored frame with FrameMaker's drawing tools. However, if you do that in a structured FrameMaker workflow and save content out to XML, FrameMaker by default saves each image with added callouts into a new CGM graphic file that no longer has editable callouts. There can't be complete round-tripping between XML and FrameMaker because the graphics aren't preserved in this scenario.

Therefore, the rule for this client is that an anchored frame can contain just one image file imported by reference. Period. No other text, text frames, or anything. If callouts are necessary, they are included as part of the source graphic; the client adds numbered callouts in Illustrator. A numbered list specifically for explaining those callouts follows the graphic.

The XML generated from FrameMaker points to the image files, and FrameMaker doesn't need to generate new graphic files to include any callouts added with FrameMaker's drawing tools. (If the directory containing XML files includes a CGM file that FrameMaker created during export, that usually means there is an anchored frame somewhere that contains something more than just a referenced image file.) Another huge plus: because the callout explanations are part of the text, they are translated without changing the original graphic.

Separating callouts from your images and making them part of the text is smart for any workflow because of localization issues, and it pretty much becomes mandatory when you're establishing an efficient structured authoring environment (and not just those based on DITA).

P.S. One other thing to think about with graphics in structured authoring environments: if you use XSL to transform your XML into online formats, determine if web-ready graphics (such as PNG files) will work in your print/PDF and online content. If so, you eliminate the need to convert images to formats for online viewing.

Labels: dita, FrameMaker, localization, structured authoring

9:00 AM Permalink | |

 

Some help with ditaval files and renegade attribute values

Thursday, December 04, 2008 — posted by Alan Pringle

Over at his Core Dump blog, Keith Soltys introduced me to the Ditaval File Generation Utility by Suite Solutions. The free utility (which is for Windows only) scans the files in a ditamap and lists values for the product, platform, audience, and otherprops attributes. You can check the list to be sure the values are right and then generate a ditaval file.

I haven't used this tool yet myself, but I can think back to a project where it would have been very helpful in tracking down just a few incorrect attribute values lurking in hundreds of DITA topic files. At the time, I used TextPad to search on all the files within directories, but I could only search on one attribute name (or flaky value) at a time. If this utility works as advertised, it would eliminate that problem.

Labels: dita

8:00 AM Permalink | |

 

Beat the post-holiday blahs

Wednesday, December 03, 2008 — posted by Sarah O'Keefe

It's never too early to start thinking about fun things to do in February.

On Thursday, February 5, 2009, at 9 a.m. Pacific Time (noon Eastern time/5 p.m. London time/etc.), I'll be offering a webinar in conjunction with Madcap Software. Not sure this qualifies as "fun," but it's better than complaining about the weather, which is our major activity here in late winter.

DITA 101: Why the Buzz? DITA, the Darwin Information Typing Architecture, is the new buzzword in technical communication. But why? In this webinar, you'll learn about DITA concepts, business case, and typical scenarios where DITA is used.

You can then evaluate for yourself whether DITA makes sense for your content. Best of all, the webinar is free, which is the right price in this economic climate.

If you are not at all familiar with DITA and want some introductory information, join me for this session.

The webinar is free, but registration is required here.

Labels: dita, madcap, presentations, xml

8:00 AM Permalink | |

 

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

Monday, December 01, 2008 — posted by Sarah O'Keefe

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?

Labels: analysis, dita, ePublisher Pro, madcap

9:00 AM Permalink | |

 

Presentations on features squeezed into FrameMaker 8

Thursday, November 20, 2008 — posted by Terry Smith

Just two weeks ago I was in an elementary school gymnasium working as an election official. Fourteen straight hours with no breaks for meals because officials aren't allowed to leave the polling area (which is why your ballot may have crumbs on it, sorry about that). In my precinct one candidate received only one vote more than the opponent; in another race, the difference was six votes. A very long and exciting day.

Bleary-eyed but pleased to have served my precinct, I spent the next two days attending the DITA/TechComm conference. Perhaps not the heady stuff of this year's election, but definitely worthwhile. This conference had two themes: DITA and the tools in the Adobe Technical Communication Suite (although Madcap Flare was definitely represented, too). The place where those two topics meet is FrameMaker.

I was scheduled to speak on two FrameMaker topics for the conference. FrameMaker 8 now has built-in DITA authoring capabilities, which I demonstrated. I had a few slides to keep the demonstration on track. The slides, which I have included here, are brief.



My recommendation? If you want to get the most from FrameMaker's conditional text capabilities, use structured FrameMaker and install the free ABCM product instead of using FrameMaker 8's Filter By Attribute feature.

Labels: adobe, conferences, dita, FrameMaker, PDF, presentations, xmetal

11:49 AM Permalink | |

 

Looking Fear Straight in the Eye

Monday, November 03, 2008 — posted by Simon Bate

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.

Labels: dita, doctraineast08, FrameMaker, xmetal

4:41 PM Permalink | |

 

Surveying the landscape

Friday, October 17, 2008 — posted by Sarah O'Keefe

Surveys are on my mind this week.

The HAT Matrix (Char James-Tanny) recently conducted a survey on help authoring tools. The raw results are available at their blog, the Mad Hatter. On the HATT list, a debate immediately erupted over whether the survey was skewed by MadCap Software.

"Intentionally skewed" is a rather loaded phrase. Let's just stipulate that the survey was mentioned by MadCap to their customers. Since Char made the raw survey results available, you can see that a little over 10 percent of the responses indicated a MadCap origin. One might assume that these participants will be heavy MadCap Software users.

If you attempt to adjust the numbers to account for this potential bias, you end up with RoboHelp and Flare basically neck and neck, whereas in the raw numbers, Flare is quite a bit higher.

And therein lies the rub. Look at the coverage that the survey is getting:

At Core Dump:

It seems that MadCap Flare has pulled well ahead of RoboHelp as the dominant help authoring tool, being used by about 40 percent of the respondents.

At I'd Rather Be Writing:

Madcap is not only a major competitor to RoboHelp, but it now seems to now have an edge on it.

If MadCap had not, um, encouraged their people to participate in the survey, we'd be seeing very different discussion. And these discussions shape perceptions.

People are also drawing the conclusion that DITA isn't happening just yet. This is possible, but the participants on the HATT (help authoring tools and technologies) list are not exactly the poster children for XML usage. We can draw the conclusion that the people who participated in this survey aren't using DITA, but I'm not too sure about anything beyond that.

In a related matter, there was a recent survey asking about structured authoring implementation. In this survey, one of the questions was about vendors/consultants who helped with implementation. It included the following seven options:

• Not Scriptorium
• Another Not-Scriptorium vendor, much smaller than Scriptorium
• A conversion specialist
• Another conversion specialist
• Yet Another Not-Scriptorium
• A Scriptorium competitor
• And finally, you guessed it, not Scriptorium

You may imagine my conniption fit. No, go ahead and double that. Throw in a tantrum and some gutter Italian words and you're slowly getting there.

By any objective measurement, we should have been included on the list.

Perceptions matter. To a prospective client, our absence on this list sends a message. It basically says that we're not relevant enough to be included. Now, it appears that we were left off because of, um, mediocre research, but that doesn't mitigate the potential damage to us.

Incidentally, in a survey on structured authoring, I'm not too sure how you do a Google search for vendors and manage to leave us out because, well:

http://www.google.com/search?q=structured+authoring

So, in conclusion, I'm not feeling too good about surveys this week.

Labels: adobe, analysis, dita, madcap

2:14 PM Permalink | |

 

DITA OT installation: check your JDK version if you're having problems

Tuesday, September 30, 2008 — posted by Alan Pringle

I have been indulging in a bit of avoidance behavior by not installing the DITA Open Toolkit on my newer laptop. Well, I broke down today and installed the latest build of the OT, but the experience was not pain free, for sure. (And it was equally not fun when I installed it on my previous computer.)

To make a long story short, I had an older version of the JDK that was causing my first test run to barf while creating XHTML output, and searching on the error messages led to a helpful blog entry:

OK, so I download and install JDK 1.4.2.18, set my JAVA_HOME environment variable, and add the location of the Java executable to my CLASSPATH environment. I restart my system for good measure, run startcmd.bat, and try to run some of the samples. The build fails, with a "java.lang.UnsupportedClassVersionError: org/dita/dost/invoker/AntInvoker (Unsupported major.minor version 49.0)" message. Arggh.

I surf over the dita-users group on Yahoo! and try to search the archives, but the search mechanism is temporarily broken. When I eventually search my e-mail locally, I find a thread that lets me know that JDK 1.5.x is required. Once this JDK is installed, the samples run as they should. I know enough Ant to quickly add a few targets to the build_demo.xml and generate the CHM and PDF files that I wanted.I installed the latest JDK and set the JAVA_HOME environment variable, and all was well after that.

I looked back at the installation documentation that's included in OT download, and it does indeed mention an old (and incorrect) version of the JDK:

Java runtime or development environment

Provides the basic environment for most tools used in this toolkit.

You can download and install the Java Development Kit (JDK) 1.4.2 (available on http://java.sun.com/j2se/index.jsp) into a directory of your choice.

The online version of the OT documentation has the correct JDK requirements:

DITA Open Toolkit is written in Java and requires at least a minimal set of Java applications be installed. Java SDK 1.5 or 1.6 must be used to execute the applications and the Toolkit Java code.

So, if your new installation of the DITA OT is failing, there is a good chance you need to update your JDK.

Labels: dita

2:02 PM Permalink | |

 

Learning the DITA Open Toolkit

Thursday, September 04, 2008 — posted by Sarah

(Scriptorium Publishing is a JustSystems Services Partner.)

Simon Bate's webinar, An Overview of the DITA Open Toolkit, is now available. This event was jointly sponsored by Scriptorium Publishing and JustSystems. The recorded version is available here (registration required).

During the presentation, we did some audience polling.

Are you currently...? (choose one)

• 31%, Using XML
• 32%, Transitioning to XML
• 16%, Planning to transition
  
• 17%, Considering a transition
  
• 3%, Not considering it at all
  

If you answered "using XML" above, what content model do you use? (choose one)

• 59%, DITA
• 0%, DocBook
• 1%, Other publicly available
  
• 10%, Developed in-house
  
• 3%, Not considering it at all

Probably not too surprising that DocBook scored 0% in a DITA-specific presentation.

I liked the last poll:

What formats do you currently or plan to publish to?

• 50%, print
  
• 92%, PDF for download
• 49%, web site
  
• 79%, online help
  
• 18%, other
  

92% are delivering PDF. We very frequently have people tell us that they "don't need print," but it nearly always turns out that they do need PDF. We operate on the general assumption that all of our customers are going to need PDF at some point, even if they don't think so, and I'm happy to see at least one data point that supports this line of thinking.

The problem, from our customers' point of view, is that producing nice PDF from DITA content is really quite challenging. (From our point of view as consultants, this is not necessarily a bad thing.) What makes PDF so challenging? Basically, you are reverse engineering your layout engine (think FrameMaker or InDesign) in the XSL-FO programming language.

Simon's presentation provides an excellent introduction to the Open Toolkit, which many find quite intimidating. This was apparent from some of the questions and comments that Simon got:

Is there a GUI for OT that could be used by documentation production staff rather than command line?

I haven't typed a command into DOS in twenty years.

What's the difficulty level of using OT to get HTML output that is more professional-looking, like a WebWorks HTML generation?

Can you please define the purpose of ANT files?

It's worth noting that running the Open Toolkit is vastly less difficult than configuring the Open Toolkit. The person doing the configuration work will need to understand Ant, type DOS commands (!), and rework the default transformation templates to produce the desired output. The person generating output with the configured OT will need to type in one command or just double-click a batch file to start processing.

Many of our customers have turned to us for the Scary Configuration Bits. If you're looking for help, keep us in mind.


This session was the second in a series of three webinars we are doing jointly with JustSystems. The last session, on September 23, will provide more details on customizing the DITA Open Toolkit. The webinar is free, but advance registration is required here. Hope to see you there.

Labels: dita, presentations, xmetal, xml

3:41 PM Permalink | |

 

XPubs: XSL-FO for Documentation Formatting

Monday, June 23, 2008 — posted by Sarah

Mike Miller, Antenna House

For starters, XSL-FO is an XML standard.

XSL-FO is "a pagination markup language describing a rendering vocabulary capturing the semantics of formatting information for paginated presentation." (Ken Holman)

Or, as I like to say, "A document layout described in a text file."

XSL-FO is black box formatting. Can't go back and "tweak" the files to fix them. With FO, you're typically talking about a minimum of a couple hundred pages. Much faster to render automatically rather than by hand in InDesign or FrameMaker.

First commercial products in 2001 from Antenna House and RenderX. Also, open source FOP from Apache in 2001. FO successful in the sense that both commercial companies are doing quite well.

FO more successful than any other technical publishing application other than perhaps TeX and FrameMaker. Probably attributable to the availability of open source (free) and trial versions from commercial vendors (free).

XSL-FO is only concerned with visual display of XML data, which means that the FO file has no semantic content, only formatting instructions.

The FO stylesheet specifies:

• page areas and sets of pages to be used to compose a document for paper (master pages)
• Text flows, areas on pages into which the text and graphics are filled
• Blocks within flow areas (paragraphs)
• Inline areas (character-level formatting)

Advantages:

• Processing and formatting are consistent and automatic.
• Formatting rules are stored separately from the data.
• FO is non-proprietary and human-readable (well, sort of)
• FO less complicated than programming Java or Perl and the like
• Can use stylesheets with different XSLT processors (DITA Open Toolkit)
• Easier integration with other XML standards compliant applications (not trivial, but much easier than other non-standard approaches)
  

Antenna House has been personally involved in about 30 different DITA projects.

Most business documents can be formatted automatically as FO. Rule of thumb: "If it's XML, FO can be applied."

Other applications for FO might include faxes, German railway tickets, correspondence from financial institutions and government.

Typesetting is very complex with issues like widows and orphans and hyphenation. Software can handle this. Human typesetters have been removed from the process, and this shows in amateurish mistakes. But you can use FO to configure something that follows typography rules and give you a professional look and feel.

"Overwhelming benefits" of using FO. Which begs the question: "Why aren't more people using it?" A slide with the benefits of XML showing The Usual (cost, time-to-market, less redundancy, standards-based, localization for cost justification, etc.).

People who use FO: auto manufacturers, cell phone manufacturers, banks, aerospace, government, military, educational

FO not appropriate for documents that are "artistically created."

FO extensions provide support for:

• Document info in PDF
• Bookmarks for PDF
• Column footnotes
• Revision bars
• MathML
• Embedding PDF within PDF
• Column rules
• Punctuation spacing
• Table autospace
• Floats
• Advanced hyphenation
• Barcodes
• several hundred extensions altogether. Antenna House uses multilingual requirements with extensions, such as special spacing requirements in Japanese or justification in Arabic through kashidas.
  

Thus, if you need one of these features, you might get somewhat locked into your rendering engine...the extensions are specific to a particular FO engine.

DITA Open Toolkit reduces complexity of getting set up and produce PDF. Could be configured and producing PDF in "a couple of hours." (Perhaps, but making it look the way you want is going to take a while.) According to Mike, somewhere between a few days and a few months, depending on the complexity of your requirements.

PDF output from DITA

• XSL-FO
• FrameMaker
• troff

Stages:

• Preprocessing. Information is parsed and assembled.
• Transformation. Formatted and generated.

Several software components are required -- DITA Open Toolkit provides all the components you need.

Why not FrameMaker or InDesign?

• Formatting is the tip of the iceberg. (WYSIWYG)
• WYDSIWYN -- What you don't see is what you need, which includes content management, automated formatting, multilingual formatting, global access, project tracking, electronic delivery, network integration

You need WYSIWYG if:

• You need to manually lay out pages.
• No fixed page style
• Need to modify page layout
• Unstructured document formats
• Document format is continuously changing
• Unstructured content
  

If you need WYSIWYG, you need a layout engine like FrameMaker or InDesign. If you need WYDSIWYN, you need XSL-FO.

On the low end, FO is free with FOP. Antenna House is most expensive at $1250 for stand-alone or server license for $5,000.

FO supports more languages than any other solution currently available.

Solving the real problem:

• Improve the total process, not just individual tasks
• Improve organizational effectiveness

XSL-FO is delivering on the XML promise. Don't underestimate it.

First question: Flowing text into typesetting engine results in line breaks that will cause readers difficulty. And this annoys him (as a professional typesetter). We want powerful, automated formatting AND the ability to do WYSIWYG tweaks. Thinks there is a role for a WYSIWYG stage after the automation bit.

I've noticed this on the BBC, too. British people ask really pointed questions.

And in response, Mike says that Antenna House has a solution for this where you create INX (InDesign XML) content (4 minutes) and then you can pull it into InDesign (half an hour), and do some cleanup.

Do all the XSL-FO tools cover 100% of the FO standard? "No, definitely not."

Labels: conferences, dita, xml, xpubs, xsl

7:50 AM Permalink | |

 

WritersUA: DITA pilot techniques

Wednesday, March 19, 2008 — posted by Sarah

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/

Labels: change management, dita, writersua2008, xml

5:29 PM Permalink | |

 

"Once you start down the DITA path, forever will it dominate your destiny"

Thursday, January 03, 2008 — posted by Sarah

Eliot Kimber has a lovely article on using DITA for narrative documents. I'm trundling through it, nodding in agreement, and then we have this horror:

[...] DITA offers at least two compelling advantages over any other candidate XML application:

1. The initial cost of ownership is low, approaching zero, and the ongoing cost of ownership is low.
2. It offers a number of sophisticated features in terms of modularity, extensibility, and linking that either are not provided by other applications or would cost a prohibitively large amount to build from scratch.

That is, the cost of applying DITA is almost always going to be significantly lower than the cost of any alternative (and at worst will be no more expensive than any other alternative).

Now, he does qualify this statement by saying that these assertions apply only if DITA is a reasonable fit for your problem. But the overall thrust of the argument appears to be that since DITA can do narrative documents (which it was emphatically not designed for), it can potentially be applied to an enormous new set of content.

Ugh.

Before I begin today's DITA-bashing session, I need to point out that we are currently using DITA for several projects here at Scriptorium. DITA slices! DITA dices! DITA advocacy raises your IQ, improves your health, and makes you irresistible. I like DITA just fine.

Moving right along...

"1. The initial cost of ownership is low, approaching zero, and the ongoing cost of ownership is low."

Just because it's free doesn't mean it's cheap. The default output from the DITA Open Toolkit ranges somewhere between unattractive (HTML) and fugly (PDF). If you care about the appearance of your final documents, you are going to have to do a lot of work to get the look and feel you want. And although the OT offers a starting point, customizing it is kind of like a trip to the dentist. The impacted-wisdom-tooth-removing kind of trip.

Getting your output working properly is Not Easy because of the, er, unique design of the OT. If the set of tags you need is small, you might be better off building a nice petite NovelML and then writing the transformations you need for NovelML instead of wrestling with DITA's complexities.

"2. It offers a number of sophisticated features in terms of modularity, extensibility, and linking that either are not provided by other applications or would cost a prohibitively large amount to build from scratch."

I agree that DITA has some lovely features in this area. However, I fail to see how they apply to the example at hand -- a narrative document such as Moby Dick. If you need modularity, extensibility, and linking features, you should consider DITA. If you don't, then these features will just get in the way.

That is, the cost of applying DITA is almost always going to be significantly lower than the cost of any alternative (and at worst will be no more expensive than any other alternative).

If DITA is overkill for your requirements, then applying DITA may not be cheaper.

But the issue that upsets me the most is this: when you attack a problem by assuming (or hoping) that DITA will work, you necessarily look for DITA features you can use. You may not think carefully about non-DITA features that you might like to have. For fiction content, I can think of several things that would be quite useful (and for which DITA offers no immediate support):

• For a book that is part of a series (like a science fiction trilogy), a listing of the entire series and an indication of where the current book falls in the series.
• Metadata to identify the point of view. Many novels switch from one narrator to another, or from a first-person point of view to an omniscient point of view. It would be lovely to filter the content to see only the first-person content (after reading the book from cover to cover as the author intended).
  
• Similarly, metadata that helps with scene location and time could be invaluable for studying literature written with numerous flashbacks. The Time Traveler's Wife and anything by Jasper Fforde come to mind.
• The ability to index by character occurrence. This is more often seen in nonfiction books, especially biographies. But imagine scanning the entire Harry Potter series for scenes with Severus Snape to determine whether his ultimate allegiance was consistent.

Of course, you could pervert and/or specialize DITA to support these and other requirements. But if you start with a DITA-shaped box, how likely is it that you will think carefully about the possibilities outside the box?

As Eliot says, the advantages of DITA can be significant. But I fear that a generation of documents will be crammed into DITA, resulting in documents that are not as well structured as they need to be.

I will now await my smackdown from the DITA Disciples.

Signed,

DITA Dissident

Labels: analysis, dita, xml

9:44 PM Permalink | |

 

2008 Predictions: They'll keep me humble in 2009

Wednesday, January 02, 2008 — posted by Sarah

Each year, I write up an internal annual report, which discusses company performance in the previous year, looks at trends, and lays out a strategic plan for the following year. Generally, this report looks great in November and December and is completely obsolete by March (at the latest). Nonetheless, I thought I'd share some of the highlights from this year's analysis. I hope you will share your agreement or disagreement in the comments.

No clear leader for DITA
DITA authoring tools are everywhere. Long-time contenders (FrameMaker, Arbortext, and XMetaL [anyone remember SoftMetal or HotMetal??]) are adding DITA feature support. Many help authoring environments are adding DITA import or export. Several companies are developing web-based DITA authoring tools, and In.Vision Research has a DITA authoring plug-in for Microsoft Word.

The tools proliferation is disconcerting. In the olden days (the early 90s!), serious technical publishing was a fairly easy choice among FrameMaker, Interleaf, and maybe Ventura Publisher. Now, some tools are on the desktop, some are in the browser, some reside inside other tools, and life is much more complex.

Will things look different in five years? Certainly. I doubt, however, that we'll be back to half a dozen (or fewer) contenders. Instead, I think DITA output will become a check-off in the same way that HTML output is now.

Reuse analyzers
Both MadCap Software and Author-It have developed reuse analysis software -- Analyzer and XTend, respectively. Most of us are familiar with translation memory tools, which try to match new content to be translated against existing content in the TM database. The reuse analyzers do similar work, but in the source language. As you write, the software compares new content to existing content and recommends matches.

This is such an elegant, obvious idea that I can't believe it's new. But I haven't seen this type of tool in desktop-level software before.

Web 2.0 integration
User-generated content, such as blogs, wikis, and forums (not to mention YouTube), is on a collision course with "professional" content, such as user assistance and documentation created by technical writers. The complaints about the amateurs butting in where they don't belong must be painfully familiar to those who remember the rise of desktop publishing software and the destruction of the vast majority of the professional typesetting business.

Note: I laid out my first magazine in PageMaker. Version 1. What little manual paste-up I did was not very attractive.

Note to young people: The expression "cut and paste" is used because in the olden days, your parents used to use scissors ("cut") and glue ("paste") to move things around on a page layout. And "strippers" didn't always use poles. But I digress...

People who are paid to create technical content need to understand what user-generated content will and will not do. (Shameless plug: I'm doing a session on this topic at WritersUA in Portland, OR, this year.)

Global business
We have our fair share of customers in North America, but an increasing number of our clients are outside North America or have significant operations in multiple locations around the world. The implications for technical communicators are global audiences, global customers (internal and external), and a requirement to work well with people from all over the world.

This is an area where I believe that U.S. communicators face some significant challenges.

Flash
I expect Flash to become the next Next Big Thing. Flash technology enables the creation of interactive applications that run in a browser (or offline with AIR, which is also fascinating). Flash is widely used for games, but for our purposes, its role in e-learning applications is more important.

Traditional classroom training is effective (when you have a good trainer), but it's also expensive and it doesn't scale well -- the more people need training, the more costs rise. And furthermore, if the students are scattered literally all over the world, the costs of assembling them all in one location are astounding. I firmly believe that e-learning is less effective than a great classroom experience (of course, I'm biased since I am an instructor myself), but e-learning has some significant advantages -- like eliminating travel requirements and reducing overall cost.

Flash has almost nothing in common with the current Next Big Thing -- XML. XML is markup, text, human-readable, and geeky. Basic Flash is like Illustrator with an extra dimension (time). Advanced Flash is an application development environment.


So there you have my list of important developments for 2008. Do you agree? Disagree? Have additions?

Labels: analysis, dita, web 2.0

2:07 PM Permalink | |

 

Why XML and structured authoring is a tough transition

Friday, May 04, 2007 — posted by Sarah

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.

Labels: dita, xmetal

10:43 AM Permalink | |

© 2009, Scriptorium Publishing Services. Legal Stuff