Random thoughts about publishing

icon Site Feed

Labels

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

Palimpsest

 

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:
I took some DITA files, opened them in Flare, made some minimal formatting changes, and published to WebHelp. The result is shown here:

Sample WebHelp from DITA through FlareNot 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:
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:
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 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: , , , ,


10:05 AM Permalink | |

divider

 

Top five reasons to like XMetal and oXygen

Thursday, June 11, 2009 — posted by Sheila Loring

Full disclosure: We're an XMetaL Services Provider and have no particular affiliation with oXygen.

I'm in the fortunate situation of having access to both XMetaL 5.5 and oXygen 9.3. Both are excellent XML editors for different reasons. I'd hate for Scriptorium to make me choose one over the other.

From the viewpoint of authoring XML and XSLT, here are my top five features of both editors:

oXygen
XMetaL
oXygen and XMetal have so many other strengths. I've just chosen my top five features.

What I'd like to see in XMetaL: The ability to indent code, the ability to drag and drop topics in the map editor.
What's I'd like to see in oXygen: The ability to view a table--lines and all--in the WYSIWYG view instead of just the element tags.

So how do I choose which editor to use at a particular moment? When I'm casually authoring in XML, I choose XMetaL for all of reasons you read above. The WYSIWYG view is more user-friendly to me. But when I'm writing XSLT or just want to get at the code of an XML document, oXygen is my choice.

Get the scoop on oXygen from http://oxygenxml.com. Read more about XMetaL at http://na.justsystems.com/index.php.

Update 6/15/09:
I'm thrilled to report that two deficiencies I reported in oXygen 9 are now supported in the latest version of oXygen -- 10.2. Two more reasons to love oXygen!

Labels: , , , , ,


1:54 PM Permalink | |

divider

 

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: , , , , ,


5:00 PM Permalink | |

divider

 

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:
DITA accounts for the vast majority of structure implementations--past, present, and futureDITA 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: , ,


10:37 PM Permalink | |

divider

 

Mechanical versus digital publishing

Thursday, January 08, 2009 — posted by Sarah O'Keefe

My last XML Strategist article (PDF) briefly mentioned Gutenberg and movable type before moving on to the focus of the article--a discussion of the implications of XML publishing and the similarities with Gutenberg's efforts. The Biblical Illuminator's Guild blog provides a much more detailed discussion of the technical challenges solved in production of the Gutenberg Bible, including:
Printer's ink. Gutenberg had to develop a new kind of ink, an oil-based one (as over against the traditional water-based ink used in manuscripts), so that it would stick better to the metal types. [...]

Font. The first part of the Gutenberg idea was using a single, hand-carved character to create identical copies of itself. Cutting a single letter could take a craftsman a day of work. A single page taking 2500 letters, crafting per page was unattainable. A less labor intensive method of reproduction was needed. Copies were produced by stamping the original into a iron plate, called a matrix. A rectangular tube was then connected to the matrix, creating a container in which molten lead could be poured. Once cooled, the solid lead form was released from the tube. The end result was a rectangular block of lead with the form of the desired character protruding from the end. This piece of type could be put in a line, facing up, with other pieces of type. These lines were arranged to form blocks of text, which could be inked and pressed against paper, transferring the desired text to the paper. Each unique character requires a master piece of type in order to be replicated. Given that each letter has uppercase and lowercase forms, and the number of various punctuation marks and ligatures (e.g. the sequence 'fi' combined in one character, commonly used in writing) the Gutenberg Bible needed a set of 290 master characters.
Read the whole thing. I think for many of us, the physical process of printing is a complete abstraction, except for the occasional toner cartridge replacement.

Contrast that with a recent article on Read/Write Web by Alex Isold, Brave New World: More Digital, Less Physical:
The main thing we learned is patterns in physical objects. We know that we can bend them under certain conditions. We know that there is friction. We know that things react differently to heat. [...] These patterns get wired into our brains and help us live our daily lives.

Computers have software inside that does not behave like physical objects do. The key thing about software is [...] that the conventional laws of physics do not apply to it. [...] It is hard for people with brains trained to deal with physical things to understand how software works.

[...]

Our kids are growing up native to this new digital world. To them, the new rules of digital physics are what the rules of physical physics are to us. They take these new rules for granted, because that is just how all our brains work.
And this interesting note in comment #20:
Your comments about how software has been designed to replicate physical effects, such as the bounce in the iPhone, are an indication that we need our software to conform to the way we see the world, not that we are beginning to conform to a new paradigm of software.
Like many of you, I grudgingly operate a Parental Technical Support hotline. My four-year-old is better at operating computers than her grandparents -- probably because she's never existed in a world without computers. For her, computers are obvious.

Now, if we look at the world of publishing, we are currently in the midst of an enormous paradigm shift. More than 1000 years ago, we replaced scrolls with books. Since then, we have been operating with books. The process of creating books has evolved from hand-copying to printing to desktop publishing, but the books themselves haven't changed much. (I did find it interesting that the Gutenberg Bible does not have page numbers. Those came along later in the sixteenth century, according to this article.) Books are obvious. We've been using them all our lives and so have our parents, grandparents, and ancestors.

In the 1980s, we shifted from mechanical production (cut and paste, galleys, etc.) to computer-based production (desktop publishing). Again, the process of creating books changed, but the end result was still a book. (Perhaps a book with horrid layout and ransom-note fonts, but that's a discussion for another day.)

And this brings me to the challenges we face today. In addition to another paradigm shift in publishing -- this time from desktop publishing to structured authoring -- we have a second, more fundamental shift. In addition to (or perhaps instead of) producing books, we must now produce digital information -- online help, wikis, forums, email, databases, and much more. We don't have hundreds of years of collective experience to draw upon in figuring out how digital information should work.

Thus, we see efforts to fall back on the book paradigm. Just as computers have "desktops" and "folders" in an effort to make them more understandable, we have e-books with "pages" and "bookmarks."

What will truly digital publishing look like when we let go of the requirements of a paper book and embrace the possibilities of digital information fully?

Labels: , , ,


8:00 AM Permalink | |

divider

 

The XML Strategist: Movable Type and XML

Tuesday, December 02, 2008 — posted by Sarah O'Keefe

My latest XML Strategist article is now available in STC's Intercom magazine. You can also read it online (PDF, 250K). An excerpt:
Gutenberg changed the economics of information distribution, and I imagine that many of the artisans who devoted their lives to creating glorious, hand-copied books complained bitterly about boring printed books.
It's my opinion that XML, like movable type, is primarily an economic innovation, and that we can extrapolate from the 15th-century reactions to movable type to make some educated guesses about how today's shift to XML will go.

Labels: , ,


12:33 PM Permalink | |

divider

 

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:
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?

Labels: , , ,


9:00 AM Permalink | |

divider

 

WYSIwar?

Monday, November 17, 2008 — posted by Sarah O'Keefe

Recently, there is a dispute brewing over the relative merits of WYSIWYG and WYSIOO (What You See Is One Option).

In the WYSIWYG corner, we have Vivek Jain, Group Product Manager, Technical Communication products, of Adobe. He recently posted this:
WYSIWYG (What you see is what you get) is the hallmark of a good authoring and publishing tool. Publishing process is the last stage of any technical communication project. Having a WYSIWYG tool, whether you are authoring for Print, PDF or HTML, enables you to preview the expected output as you develop the content and reduces surprises in the end. Surprises during the publishing stage are often the reason for project delays and nightmare for all project members.
And in the WYSIOO corner, we have Sean Wheller with an excellent overview of the argument for XML, which includes a discussion of WYSIOO and WYSIWYG:

[The WYSIWYG] approach is not possible with XML since it was designed to describe data and to focus on what data is, not how data will be displayed or formatted. Authors composing texts stored in XML must use a "Structured Editor." This means the editor is focused on two tasks: text composition and valid markup thereof. Since formatting information cannot be saved inside the XML file, the best an editor can do is render temporary formatting and layout for the duration of the editing session. What authors see during the editing session is "One Option" of what they may get in the final product, WYSIOO.

WYSIOO and WYSIWYG are opposite ends of the same stick. The two end-points cannot be brought together without breaking the stick. Try as you may, if you do manage to bring these polarities together you will find that you have violated the fundamental laws of one or both of these paradigms.

Jain counterpunches:
[W]hile authoring XML documents in FrameMaker, the styles are applied through a template. [...] You can replace your [...] template at any time during authoring or publishing.

I have often found the argument about WYSIOO (What you see is one option) very hard to understand. If you are publishing for two channels, you can use two templates to preview the final output (WYSIWYG view for two channels). In any case, you need these two templates for publishing, why not share these templates with the authors.

[...] If you can get WYSIWYG for both print and HTML and synchronized content, isn't WYSIOO an argument in favor of poor authoring experience.
And this is where I join the fray and attempt to provide some additional perspective. WYSIWYG has been the norm for around 20 years as part of the desktop publishing paradigm. Desktop publishing became the dominant paradigm for lots of fun reasons that I won't get into here. (Wikipedia has the scoop, as usual.)

Today, the entire publishing industry is in the throes of a shift from desktop publishing to structured authoring. Our Structured Authoring and XML white paper has all the gory details. When you start focusing on document structure rather than on page (or screen) presentation, your priorities change.

Dismissing WYSIOO as simply a "poor authoring experience" is too simplistic. In a collaborative, distributed, modular authoring environment, it may be impossible to provide a WYSIWYG view because each end user might see a different version of a document. A simple example would be a web site that allows different users to choose the look and feel of the document instead of accepting the formatting choices that the web site developer made. For print, the final pagination of a document would depend on which modules are assembled for the document, and if the end user has the ability to choose which content to include, the author can't predict where the page breaks will fall in the document.

Finally, there is the question of the author's mindset. If you author in an environment that shows you a WYSIWYG print representation of your final document (as in FrameMaker), would that cause you to focus more on printed deliverables rather than considering all the possible destinations for your content, such as print and PDF (which could be different!), HTML, CHM, Eclipse help, and so on?

We are moving away from providing static deliverables, such as HTML pages or PDF files. Instead, readers may be able to control presentation, change fonts, aggregate content, and assemble their own deliverables. In this environment, we need WYSIOO.


PS I'd really like to know who coined WYSIOO. The earliest reference I've found is 2004.

Labels: ,


4:00 PM Permalink | |

divider

 

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:

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: , , ,


2:14 PM Permalink | |

divider

 

Taxonomy of web content delivery

Thursday, September 11, 2008 — posted by Sarah O'Keefe

I really like the new article from Richard Hamilton on the Content Wrangler, in which he describes various categories of web content delivery, ranging from "no-ware" to "shovel-ware" to "active-ware."
Active-ware is "anything that lets you interact with users online." And most interestingly, Hamilton points out that:
Active-ware is orthogonal to the other categories and suggests that successful approaches to Active-ware will draw from a different set of models than the other categories.

You might also describe "active-ware" as Web 2.0 content. In which case, you might find our Friend or Foe? Web 2.0 in technical communication white paper of interest.
(Side note: These white papers are now available as HTML and you can rate each page and leave your comments.)
Hamilton implies that the role of the technical writer will change for Web 2.0 content (active-ware). He writes:
[... S]ome of the things we value most in technical communication, like good writing and complete and accurate solutions, may have less importance, if any, in Active-ware.

I started my career in technical communication as a production editor. Technical writers wrote content, technical editors reviewed the information for grammar, mechanics, and completeness, and the production editors were responsible for verifying that the documents were formatted correctly and printed properly.
These days, production editors and technical editors are endangered species. Some organizations have eliminated production editors with automated formatting (usually an XML-based workflow); other organizations place the responsibility for final document appearance on the technical writers. In neither case do we have people whose primary responsibility is to give content that final gloss.
As a former production editor, I find this unfortunate -- and the formatting errors that are so abundant in today's technical content make me cringe. But from a business perspective, I understand the reasoning -- for most organizations, the value added by checking pagination, fixing awkward line breaks, and verifying formatting is not great enough to justify the expense. (A few organizations, especially those in consumer electronics and similar industries, still emphasize high-quality printed manuals.)
Which brings me back to active-ware, which is often of lower quality than traditional technical communication because it's poorly written, not complete, and not entirely accurate (as Hamilton says in the quote above). Active-ware, however, has one huge advantage: immediacy. On a forum, you can ask a question and expect help within hours or even minutes. If the documentation doesn't address your particular issues, waiting months for the next release of the documentation is probably not a viable solution.

Labels: ,


10:13 AM Permalink | |

divider

 

Tout de Suite...too many suites?

Wednesday, September 10, 2008 — posted by Sarah

You may have missed Madcap's recent announcements of their sundry product upgrades somehow. Perhaps you were on a deep-sea expedition or out in the desert? I fully expect, though, that you would have received an announcement from Madcap via SMS on your satellite phone. But I digress...the topic of this post is not supposed to be the awesome power of the Madcap Marketing Machine™.

The Adobe Army has the Tech Comm Suite to face off against the MadCap Minions with their MadPak. Adobe's marketing is a little less...um, aggressive than their competitor. And let's not forget Author-it, which describes Author-it itself as a tightly integrated product suite.

So many suites...so little time. I feel like a kid in a candy shop. (And I'm a bit of an expert on candy shops.)

Except for one problem. Take a look at my top three requirements for authoring software:
None of the suites do these things. Oh sure, MadCap and Author-it save content in XML (really, XHTML, but who's counting) and FrameMaker can validate against arbitrary structures.

But as I've said in many publications and presentations
, the current trend is to take away publishing responsibilities from content creators. Instead of authoring books, authors are creating bits of content, which are then assembled into the final deliverables. And the use of a suite seems to go against that trend because authors are once again placed at the center of the publishing effort.

Am I the only one who would like to see a shift in focus?

PS I apologize to the French language. I am well aware that I completely murdered the translation of "tout de suite" -- which actually means "right away." I'm afraid I'm just powerless against the joy of really bad puns, especially really bad multilingual puns.

Labels: , , ,


3:14 PM Permalink | |

divider

 

A cautious toe in the water

Tuesday, September 09, 2008 — posted by Sarah

[Updated to add link to Gilbane Group, which I accidentally left out. -Sarah]

Over at the Gilbane Group blog, Fred Dalrymple writes about social media, aka Web 2.0, aka user-generated content:
Integration [with technical documentation] means, somehow, placing social media into an iteration loop in the documentation supply chain.
He believes that a prudent first step could be to work with customers:
For example, it's easy to imagine deploying a documentation set via a wiki that issuing and client companies can both update, perhaps with a dedicated editor at the source company to keep brand, message, and metaphors consistent. That leaves the challenge of how that material gets integrated back into the supply chain so that it can feed the next release...
These are early thoughts, and tools such as wikis are low-hanging fruit. How will the less document-centric media be integrated? What new forms of relationship will develop around these practices? How can this be extended to independent outsiders?
It sounds totally reasonable. But the general focus of the post is on controlling branding and message. And I believe that the general implication of Web 2.0 and many-to-many publishing is that corporations are going to lose the ability to control the conversation.

Dalrymple says:
Let's assume that when social media is being practiced by independent outsiders, it will be a matter of chance whether their behavior is consistent with a corporation's goals.
This misses the larger point. If the end users want the corporation to have different goals from what the corporation actually has, the corporation will need to respond! The answer is not to control, direct, and manipulate social media so that it conforms with the preferred brand messaging. The answer is to recognize that the corporation's goals need to change.

For example...let's say that a company releases a new operating system. Let's call it, oh, "Vista." And perhaps the company's goal is to sell this "Vista" to the entire world. But users respond by heaping scorn on the new release, demanding downgrades the previous operation system, and, most drastically, switching to other operating systems.

The problem is not those mean, angry bloggers writing rude things about the product. The problem is with the product.

If the social media world is telling you things that are not compatible with your brand and product positioning, it means that you have a problem with the brand and the product -- not with the users.

Labels: ,


12:40 PM Permalink | |

divider

 

Web 2.0 and Truth

Thursday, June 26, 2008 — posted by Sarah

My presentation at X-Pubs was about the impact of Web 2.0 or user-generated content on technical communication. (You can view the presentation at the bottom of this post.)

A phrase I heard repeatedly in reference to professional content was "a single version of the truth," which alludes to the idea that you should only have one instance of any given piece of content.

And that got me thinking. There are many areas of tech comm where this idea makes sense.

User-generated content, though, is in direct conflict with a single, unchanging, objective truth. Wikis, by definition, have content that is constantly evolving.

Furthermore, there's truth and then there's, well, truth. Compare and contrast these two snippets:
"The ABC feature is unusable. Use the XYZ as a work-around."

"You can use ABC to do blah blah. Here's how:
(many annoying steps)"

Which one is truth? Both? More importantly, which one is more useful to the reader?

It takes a brave or maybe foolish corporate technical writer to criticize their own product explicitly. (This, in turn, is probably why third-party computer trade books sell so well. Somehow, I don't see a title like Word Annoyances getting the Microsoft seal of approval.)

But even though technical writers try to act as user advocates, there's a built-in conflict of interest -- technical writers are paid by corporations, not by users.

User-generated content meets a need that corporate technical publications do not (or perhaps cannot). It provides unfiltered, opinionated, and user-biased coverage of technical topics.

Why is there a gap between professionally created technical publications and the end users?

1. Updates can take a long time to get into the official documentation because of lengthy review, approval, and publishing processes.

2. Annotation capabilities are rarely provided to users. If they are, they're usually fairly limited.

3. The documentation is not sufficiently candid.

What are the implications for technical writers?

1. Document publishing needs to accelerate.
2. Online documents should allow for comments and discussion.
3. The documentation needs to be explicit about product limitations and workarounds.

In effect, technical writers need to have more of an editorial voice.

Here is my Web 2.0 presentation:







Notes: Use the arrow keys to navigate through the slides. The first slide may take a few seconds to come up; the presentation file is quite large.

Labels: , , ,


11:21 AM Permalink | |

divider

 

A Quarky new approach?

Tuesday, May 13, 2008 — posted by Sarah

Recently, Quark has announced their new dynamic publishing concept and/or solution.

Where to start?
Although traditional publishing allows each author to hand-craft the appearance of each page, the limitation is that it ties information to the way it is presented. This means that if you want to publish the same information in print, Web, and electronic formats, then you have to create an entirely separate version of your information for each media type.
Fascinating, but it sounds oddly familiar. Where could I have heard this before? Wait! This sounds like an argument for...single sourcing!
[S]ingle sourcing means writing information once
and using it many times. It does not mean writing it and
then copying and pasting it into another source, or modifying
the information for different needs such that you have
multiple sources.
That would be from The Impact of Single Sourcing and Technology by Ann Rockley, published in Technical Communication in 2001.

The term "single sourcing" also appears in Designing Windows 95 Help: A Guide to Creating Online Documents, which was published in 1996 (!). You can see excerpts via Google Books. I'm sure there's more, but 1996 is plenty early.

Anyway, back to Quark:

Dynamic publishing is a different way to create and share information. Dynamic publishing lets you create information as reusable components of information that you can easily combine for different uses - different types of documents and different audiences.

Dynamic publishing also automates the page formatting process, so you can automatically produce print, Web, and electronic content from a single source of information.

Sorry, guys, but what you're describing is "single sourcing" and it's been around for a while. And I don't think redefining "dynamic publishing" is going to work, either, because that term already means something. Dynamic publishing can refer to the following:
Wikipedia has a definition of dynamic page publishing. RR Donnelley has dynamic publishing products. Here's a discussion of low-end dynamic publishing inside Six Apart (blogging platform). The RenderX engine has dynamic publishing ("For high volume, mass composition of personalized correspondence..."). For one-to-one marketing, we have PageFlex from Bitstream and Fusion Pro from Printable. Here's Arbortext and their discussion of dynamic publishing.

Arbortext. Hmmmm. There's something about Arbortext....

And here is where the situation gets truly weird. Take a look at the Quark executive biographies page. Of the ten people listed, five are ex-Arbortext, including the CEO, CIO, marketing VP, and two of three sales VPs.

So, Quark is the recipient of some sort of a multiple-organ management transplant from Arbortext. Given the rumors that the Arbortext-PTC merger hasn't been exactly a lovefest, the departure of senior management and others isn't surprising. It's their reappearance at a single company that's striking. And furthermore, it appears that they are trying to create Arbortext, MarComm Edition.

Will this work? The landscape is pretty bleak.

Here is an excerpt from Eric Kuhnen's analysis (published on TheContentWrangler.com, and you should read the entire thing):
Quark, in proposing to integrate a CMS into its Dynamic Publishing Solution, has just added a well known set of problems to their offering. There are literally dozens of CMS-enabled solutions on the market already; Quark’s entry is nothing new (well, it is to Quark but not to its customers). It’s not that adding the CMS itself is the wrong idea, but that incorporating a traditional CMS will yield fewer benefits to the customers in the markets it serves, and will not do much to displace the leading ECM vendors in the markets it would like to serve. So, Quark will follow the road it has always taken.
(Emphasis mine)

A variation on this theme is found in an interview with Raymond Schiavone conducted by Pariah S. Burke, editor of QuarkVsInDesign.com (again, read it all, especially the analysis of the interview on the third and fourth pages). This excerpt is from Burke's analysis:
I think QuarkXPress will continue to have utility on its own, but its primary role will be to function as a desktop client for an as-yet unrevealed enterprise-grade suite of systems.

XPress 8 will be the first stage, I predict. [... Schiavone's] realistic goal for the XPress 8 generation of products will be to make the market take notice of Quark again, to open a dialog with large workflow managers who will help refine Schiavone’s vision for XPress 9.

By the time XPress 9 and its matching systems do release (probably less than 12 months following the release of version 8), QuarkXPress will be little more than a client application. All the real power will reside on the server-side systems. More importantly, by abandoning the so-called “feature war” with InDesign, Quark will create a lopsided conundrum for potential users—you can have near total automation of your publishing and production, with output to print, PDF, PDF/X, HTML, XML, and everything else you can think of, but without certain creativity, composition, and proofing features the competition will have had for generations.
The existence of InDesign Server notwithstanding, I think the overall analysis makes sense. Basically, transitioning Quark into a server-based publishing system requires moving away from freelancers and small business customers. They can't afford and don't need server-based publishing. Instead, Quark needs to make inroads into large companies with large marketing departments. And there, they run up against the twin buzzsaws of InDesign and existing competition in the content management space. This might work if Quark's offering was deeply compelling, unique, and game-changing. In its current version, it appears to be none of the above.

The most difficult part of any change in technology is end user adoption. I've discussed change management on this blog and elsewhere. Bringing XML and automation into a marketing or publishing workflow is going to present some unique challenges.

In publishing (not technical publications), the deliverable is in fact the product. As a book publisher, you care greatly about the appearance of your final product, the book. In technical publishing, the appearance of the documentation is often negotiable, and making the inevitable compromises on formatting to get better automation is an acceptable tradeoff. This may not be true for most magazine and book publishers. (It's worth noting that the most technical of trade book publishers, O'Reilly Media, was also the first, as far as I know, to move to XML-based publishing.) Quark grudging acknowledges the challenge in the description of their solution:

Dynamic publishing started in the realm of technical documentation, where large manufacturers and some types of publishers have implemented dynamic publishing to produce user guides, service manuals, parts catalogs, legal documentation, and similar types of information.

Some publishers have built their own dynamic publishing systems for publications that have more elaborate layout requirements than technical documentation, but these systems have been cobbled together from multiple technologies. In many cases, they have achieved some of their business goals but at the expense of far higher process costs.

"Cobbled together"?

"Pot? This is Kettle. How you doin'?"

Here is a description of what's in Quark's DPS (from the Quark DPS FAQ)
Quark Dynamic Publishing Solution (DPS) is publishing software. It consists of multiple software components, some from Quark and some from third parties, including:
  • Optional desktop products for creating content: QuarkXPress, QuarkCopyDesk®, Xpress™ Author for Microsoft® Word, Adobe® InCopy® and InDesign®
  • Standard server-based publishing software: QuarkXPress Server and Quark Transformation Engine, for publishing to print and electronic media
  • Standard server-based product for automating workflow: Quark Publishing System
  • Optional browser-based product for content creation, final document edits and reviewing
  • Integration with server-based products for content management partners such as Alfresco®
(emphasis mine)

visual of Quark Dynamic Publishing System from Quark
(Image from Quark's web site: http://dynamicpublishing.quark.com/dps/how_it_works.html)
OK. Moving on.

Here is a really accurate bit of information. In response to the question, "How will dynamic publishing affect me and my employees?", we have this:
The primary impact is on the authoring process. Dynamic publishing shifts the authoring focus from hand-crafting pages to creating information that is independent of any specific media type, which means that authors stop worrying about how the information looks and instead focus on writing it. Authors also shift from creating monolithic documents to writing small, reusable components of information.
There is a world of pain hidden in those three sentences. In my experience, the more creative technical writers have a more difficult time with XML than the more engineering-oriented writers. Let's graph from most technical to least technical:

engineers >> technical writers >> marketing writers

Uh-oh. Getting marketing people to follow structured authoring concepts is going to be really difficult.

A couple of final notes:
All in all, I'm none too impressed with Quark DPS version 1. Now, if the "dynamic publishing" bit in the name is a preview of coming attractions rather than an accurate label for what they have now, then perhaps there's hope. But I'm glad I'm not the one trying to pull this off because from out here, it looks like an extreme long shot.

Labels: , ,


2:55 PM Permalink | |

divider

 

DocTrain: Document Engineering in User Experience Design

Thursday, May 08, 2008 — posted by Sarah

Bob Glushko
blog: Doc Or Die
University of California, Berkeley

Has a history as a consultant in hypertext (Hypertext Engineering), Passage Systems (single-source publishing and SGML), and then Veo (business-to-business commerce stuff), which was purchased by Commerce One. "And I made a gazillion dollars."

He has just started a company called Document Engineering Services.

What is document engineering?
Designing the information models and repositories that enable document-centric applications.
Building an information supply chain
Examples: tracing lettuce origins because of contamination concerns, simplifying passenger travel (and then some wildly entertaining attacks on TSA, the agency everyone loves to hate), integrating web-based stores and retail stores (purchase something online and return at the local store)

Information tech and business process are co-evolving
Document exchange patterns
Interesting discussion.

Document design questions are fundamentals.

"Drop shipment" pattern
* web store takes the order and validates it
* warehouse has the stuff
* web store notifies the warehouse
* warehouse ships the stuff

"hidden documents in business processes"

overlapping info models from shipping note, purchase order, transaction advice

traditional design approaches were preventing him from seeing the whole problem. Focus on documents is wrong. Need to focus on user experience -- not the interface, but Did the Product Arrive on Time and was the order fulfilled properly? Does the right person pay? Does it go to the right address? Did it arrive on time?

Traditional User Experience Design
* emphasis person-to-person interaction
* focuse on touch points where service is delivered or received
* implies that a richer or more personalized user experience is usually better

The need to bridge the "front stage" and "back stage"

* focus on the service encounter implies a sharp distinction between the interaction between customer and provider and what makes the interaction possible.

compare restaurant experience: MacDonald, gourmet restaurant, Japanese steakhouse -- amount of "front stage" varies greatly.

"Radical Claims Start Here"

* Many design ideas and methods need to be substantially rethought.
* Moment of truth reveals service quality but rarely determines it.
Front stage/back stage is not an architectural distinction -- it is just a point of view.
* It embodies some design biases that cause problems in service system design.

hotel service
* quality of check-in service
* Ritz higher than Motel 6
but missed the point of quality of experience.
Losing the reservation: Bad. No amount of nice will help with that.
kiosk check-in: low interaction/high quality

four encounters at hotel check-in:
* employee looking up reservation
* hotel systems talking to Expedia
* and some others I missed

all have to work for the front stage to work properly
quality is enabled or constrained by all of the service encounters.
even though many encounters don't involve or are invisible to the customer

service encounters are information exchanged
* person-to-person and machine encounters are less different than you might think.

Service system
* abstraction of service encounters are information exchanges

front stage/back stage distinction is a point of view
tension between front and back stage is not intrisic
merge the mindsets between front and back
services should be modular and configurable
information flow and process models across both
actionable user models
model-based user interfaces

customization and personalization
what information is required to do this?
where can this information come from?

ask question or fill out form?
one form or many over time
how about using information we can already to make it unnecessary to collect information from the user

mass customization/segments of one

model-based UI and UX

personalized banking...specific accounts but generic offers

traditional service design concepts -- moment of truth, front stage/back stage

need a methodology for designing service systems that are more horizontal or end-to-end
all services can be viewed abstractly as information exchanges.

Very interesting presentation.

His book is Document Engineering.

Labels: ,


1:43 PM Permalink | |

divider

 

WritersUA: Pundits panel

Wednesday, March 19, 2008 — posted by Sarah

The pundits' panel is always fun and usually slightly wacky. The panel this year was Alan Houser (Group Wellesley), Scott DeLoach (ClickStart), Bogo Vatovec (Bovacon), and Kevin Siegel (Icon Logic).

Tools and technologies

Alan Houser: XML-based authoring and publishing will remain a niche component among user assistance workflows. Alan points out that XML-based tools do not match the features of conventional authoring tools and haven't achieved substantial market share. Thus, he expects that this will remain a niche approach.

[I would have to disagree strongly with this. Organizations are implementing XML despite the challenges with the authoring tools. As the tools improve (and they HAVE TO because surely it can't get a whole lot worse), they will become less of an obstacle and thus open up XML-based authoring to more people. In our business, we are seeing demand for XML-based authoring across every possible industry, company size, and content type.]

Kevin Siegel: Adobe will develop the Tech Comm Suite for the Mac

[Sorry, Kevin, I suspect this is wishful thinking. I'll be happy if you're right, though.]

Bogo Vatovec: User assistance technologies need to bridge the gap between readers and creators and support user-generated content.

[Is this a prediction? It seems like more of a feature request. But I would have to agree that this is needed and will probably happen.]

Aha. The tools aren't so great and it's the help authors fault because we're asking for the wrong features.

Scott DeLoach: Within seven years, your applications, your files, and almost everything else will be web-based. (And also, PCs, phones, cameras, and GPS systems will converge.)

[Yes. This is already happening with GPS-enabled phones and the like. I'm not too sure about the seven-year estimate, but the convergence assumption seems reasonable. And the move to the web is clearly already underway.]

Scott thinks that we won't have RoboHelp for the Mac, but that RH will run on the Mac because it will be web-based!

Joe Welinske thanks Scott for "going out on the edge there" with a prediction that "in seven years, gadgets will be smaller." Hee.

User Assistance

SDL: Within five years, all software UA will be embedded or web based. Web-based content means only one copy and updates are immediate. Other web-based UA will become part of the help -- wikis, discussion groups, FAQs, and the like.

[That seems uncontroversial. Next?]

KS: Unsociable help systems won't be invited to the party. Today's students want to be fully engaged by media and games. He predicts the era of "rich media." If your help system isn't dominated by interactive commenting and interactive media, it will be irrelevant.

[This may be true for tools that are optional (think Quicken), but not so much for tools that are needed to do your job (not optional).]

BV: Introverted technical writers will not be writing help any more and will be replaced with experts moderating support forums. Companies should focus on enabling search of user forums rather than on help development. Technical writers can no longer afford to hide in their cubes, they must go out and become experts and talk to the users. At this point, they are support engineers rather than technical writers.

[Second reference today to "not providing obvious information" and instead focusing on important information.]

AH: Rich Internet Application technology will fill the current void in help delivery engines.

Lots of stagnation in the help delivery tools and mechanisms, but more innovation in the last year. The logjam seems to be breaking with the new RIA technologies, such as Adobe AIR.

[Totally agree with this.]

Joe: "The majority of the help created in the last 20 or 30 years is pure crap because it was created by people who would much rather be doing anything else." But the people in this room are creating much better stuff, he says.

Bogo definitely struck a nerve with his comment about not being introverted. Several comments about how introverts can TOO do this job.


IT Industry

SDL: Within 10 years, the web will not be free. Access devices and access will be free or inexpensive. Free web access will include ads on pages and ads at set intervals.

[Interestingly, that's exactly the model that the "free municipal WiFi" in Portland uses. You can access the web for free, but you get a sidebar full of ads, and an occasional interstitial ad (interspersed when you try to follow a new link).

I hope he's wrong about this one, but I've got a bad feeling that he's probably right.]

KS: Smaller training companies could virtually meet their demise. Companies must add virtual classes and eLearning. This puts the responsibility for the software on the student instead of the training company. The technology works, the bandwidth is available, and the cost of hosting online meetings is reasonable.

[We are offering a significant number of classes online, and I suspect that this is true. Although classroom learning is better than web-based instruction, it's also a lot more expensive. So, web-based training provides a cost-effective alternative and removes a lot of the friction associated with travel required for classroom learning.]

AH: The quality of machine translation will improve dramatically within 5 years and will match the quality of human translators within 10 yeras.

[Oh, not a chance. (Usually, I agree with Alan on stuff. Not today.) However, it may be that machine translation will become "good enough." Hand-crafted translation may be reserved for high-impact documents rather than for "utility" documents.]

BV: Computers as we know them will disappear. We will have one-for-all devices, specialized devices, and embedded computers. Additionally, the oddest devices, like kitchen ovens, have full computers embedded. So the challenge is to figure out how to provide user assistance for the oven?

Bogo thinks that we will not "pay for access to the Internet" as Scott said, but instead that we will "pay to get non-crappy content."

Fun panel to round out a great conference!

Labels: ,


7:51 PM Permalink | |

divider

 

"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):
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: , ,


9:44 PM Permalink | |

divider

 

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: , ,


2:07 PM Permalink | |

divider


Scriptorium Publishing | Post Office Box 12761 Research Triangle Park, NC 27709 | (919) 481 2701 | info@scriptorium.com