Skip to main content

Industry insights

DITA Industry insights

Flare 5 DITA feature review, part 2

[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=”https://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:

screen shot showing Related concepts heading in red and with sentence style capitalization
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:

audience.admin and audience.user conditionsI 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.

Sarah O'Keefe
June 17, 2009
Read More
DITA DITA-OT Industry insights

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

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

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:

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

&lt;topicref href="introduction.xml" navtitle="Introduction" type="topic"&gt;

Flare picks up the “Introduction” from the navtitle attribute.

Inside the file, you find:

&lt;title&gt;Executive summary&lt;/title&gt;

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.

Sarah O'Keefe
June 12, 2009
Read More
DITA XML—authors Industry insights

Top five reasons to like XMetal and OXygen

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

  • Apply XSLT on the fly: You can associate an XML file with an XSLT and transform the XML within oXygen. Goodbye, command line! XMetaL will convert the document to a selected output format. You don’t choose the XSLT–it hasn’t been a big concern for me.
  • Indented code: The pretty-print option makes working with code so easy. You can set oXygen to do this automatically when you open a file or on demand. The result is code indented according to the structure. XMetaL doesn’t have pretty print.
  • Autocompleting tags: As you type an element, oXygen pops up a list of elements beginning with the typed string. You press Enter when you find the right tag, and the end tag is inserted for you. The valid attributes at any particular point are also shown in a drop-down list. XMetaL doesn’t have autocompleting tags.
  • Find/replace in one or more documents: I’ve often needed to search and replace strings in an entire directory. In XMetaL, you can only find and replace in the current document.
  • Comparing two documents or directories: Compare files by content or timestamp. In a directory, you can even filter by type so only XML files, for example, are compared. XMetaL doesn’t offer this feature.

XMetaL

  • Auto-tagging content: You can copy and paste content from an unstructured document (a web page, for example), and XMetaL automatically wraps the content in elements. Even tables and lists are wrapped correctly. This can be handy if you have a few documents to convert. In oXygen, the content is pasted as plain text.
  • Auto-assignment of ID attributes: Never worry about coming up with unique IDs. XMetaL will assign them to the types of elements you select. Warning: The strings are quite long, as in “topic_BBEC2A36C97A4CADB130784380036FD6.” oXygen only inserts IDs on the top-level element but full support will be added in version 10.3.
  • Auto-insertion of basic elements: When you create a document, XMetaL inserts placeholders for elements such as title, shordesc, body, and p. It’s a small convenience. oXygen will also insert elements if you have Content Completion selected in the Preferences.
  • WYSIWYG view of tables: The table is displayed as you’d see it in a Word or FrameMaker document. In oXygen, all you see are the table element tags.
  • Reader-friendly tag view: The tags are a bit easier to read in XMetaL than oXygen. In XMetaL, the opening and closing tags are displayed on one line when possible. This feature saves space on the page and makes the document easier to read in tag view. For example, you might have a short sentence wrapped in p tags. In XMetal, the p tags are displayed on the same line. In oXygen, the p tags are always on separate lines. This is another convenience that doesn’t sound like a big deal, but it really makes a difference while you’re authoring.

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.

  • In Author view, tables are now displayed in WYSIWYG format. Just like in your favorite word processor, you can drag and drop column rulings to resize columns. After you resize columns, the colwidth attribute in the colspec element is updated automatically. This is much easier than manually editing the colwidth.
  • In Author view, the tags are now displayed on one line when possible. Before, the tags were always on separate lines from the content.

Two more reasons to love oXygen!

ScriptoriumTech
June 11, 2009
Read More
DITA DITA-OT Industry insights

DocTrain’s demise and a challenge to presenters

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:

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.

Sarah O'Keefe
May 18, 2009
Read More
Industry insights

Life in the desert

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.

Demystifying DITA to PDF Publishing

View more presentations from Scriptorium.

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.

Sarah O'Keefe
March 23, 2009
Read More
Industry insights

Review of screen capture programs

by Sheila Loring

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

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

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

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


ScriptoriumTech
February 17, 2009
Read More
DITA Industry insights

Looking Fear Straight in the Eye

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

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

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

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

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

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

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

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

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

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

It’s not that scary.

Simon Bate
November 3, 2008
Read More
Industry insights

TOC: Tim O’Reilly/Publishing 2.0

What do killer Internet applications have in common?

  • Information businesses (publishers??)
  • Software as a service
  • Internet as platform
  • Harnessing collective intelligence

Web 2.0: harness network effects to get better the more people use them.

  • Google: every time someone makes a web link, they contribute
  • eBay: critical mass of buyers and sellers hard for others to enter
  • amazon: 10M user reviews
  • craigslist: self-service classified ads, users do all the work
  • YouTube: viral distribution, user creation, user curation

Each of these companies is building a database whose values grows in proportion to the number of participants — a network-effective-driven data lock-in. (gulp)

Law of conversation of attractive profits

  • When attractive profits disappear at one stage the opportunity will usually emerge at an adjacent stage.
  • PCs used to be expensive. Software became expensive. Free precursor to rediscovery of value in some other form.

And thus, if digital content is becoming cheap, what’s next? What’s adjacent?

For publishers, the question is: where is value migrating to?

Asymmetric competition

  • craigslist has 18 employees, #7 site on the web (2005 numbers)
  • All others in top 10 have thousands of employees.

Curating user-generated content

  • The skill of writing is to create a context in which other people can think. — Edwin Schlossberg
  • The skill of programming is to create a context in which other people can share.

Collaborative authoring

What job does a book do? What is a book’s competition?

  • Harry Potter’s competitor is World of Warcraft
  • Encyclopedia Britannica — Wikipedia — Google
  • Books compete with information available online
  • Teaching/reference/edutainment

Search is most important benefit of content being online

“Piracy is progressive taxation”

  • Benefits the books at the bottom that would be lost
  • How to balance/manage a progressive taxation system
  • Gain more sales on the bottom end

DRM: “Like taking cat to a vet” (hold them very carefully and loosely!)

More options = happier users

Sarah O'Keefe
June 19, 2007
Read More
Industry insights

TOC: Chris Anderson/Free: The economics of giving stuff away

Chris Anderson, editor-in-chief, Wired Magazine

The cost of things tend to fall to zero over time.

You can build business around giving things away:

  • Free samples
  • Skype, YouTube, free unlimited storage on Yahoo
  • Ad-supported media..product is free, make it back on ads
  • Free ice cream samples
  • Give away razor, sell blades
  • Gift economy/wikipedia, craigslist: people donate expertise/time for nonmonetary — attention, reputation, expression…never before “dignified” as an economy. There is an economy, just money is not the currency.

If marginal cost of reaching the N+1 customer is approaching zero, then treat the product as free and figure out how to sell something else.

The price of a magazine like Wired is arbirary; it bears no relationship to the actual cost of the magazine. The subscription price is intended to qualify your interest. Setting the price too low “devalues the product.”

Most music is free. “Free as in speech” — DRM is going away. “Free as in beer” — bands are experimenting with giving away music to market the live performances.

Games and movies would be free if not protected. They are locked down to enforce prices. Artificial barriers tend to fall over time. Already seeing ad-supported videogames. (neopets)

The shining exception: Books! They are not asymptotically approaching free. Books make sense. They provide the optimal way to read. The physical product is better than digital product…excellent battery life, screen resolution, portable, and it even looks good on your shelf. Easy to flip through.

If “free” is “the business model of the 21st century,” how could a book be free?

(This was preceded with a disclaimer that many of these options would be “offensive” to people in the audience.)

For his next book, Anderson wants to do the following:

  • Audiobook will be free with book (mp3) (free coupon in real book)
  • Will participate in book search, include Google
  • Considering an e-book locked to a specific reader for free
  • Unlocked e-book with advertising inserted
  • Book online with ads in the margins
  • As many sample chapters as publisher will accept

How could a physical book be free?

  • Sponsored book
  • Consultants give away books
  • Book with ads
  • Free rebate
  • Free to influentials/reviewers
  • Libraries have always had free books

Why do it?

  • Free book is marketing for the non-free thing
  • Book is marketing vehicle for celebrity
  • Can’t give away time
  • If free version is inferior, you give it away to market the better product
  • Use “free” to maximize reach to new influentials

Why aren’t more people doing free content?

  • Most people are not represented by a speaker’s bureau and can’t monetize fame
  • Online sample is not a compelling example of book (maybe for cookbook, probably not for novel)
  • No natural advertiser
  • Publisher opposition — publishers not in business of selling celebrity
  • Annoys the retailers
  • Fear and timidity/fear of cannibalization

The most critical point: The interests of the author and the publisher are critically misaligned. Publishers doesn’t benefit from speaking fees of consulting fees, only from book sales.

Sounds like an argument for self-publishing to me.

Sarah O'Keefe
June 19, 2007
Read More
Industry insights

Tools of Change for Publishing/Norwegian Monks!

As part of a brief history of publishing in the opening keynote, I’ve already seen a few friends:

  • The Norwegian Monks video — Technical support for books
  • A reference to Vannevar Bush’s “As We Might Think” article from 1945

According to Tim O’Reilly, Microsoft Encarta “fatally wounded” the Encyclopedia Britannia because of “asymmetric competition.”

A series of short, related keynotes to kick off the conference. I like this approach; in a nontechnical, high-level keynote, it can be difficult to fill a 60- or 90-minute slot.

Brian Murray, HarperCollins, Retooling HarperCollins for the Future
Consumer publishing *was* straightforward. All promotion wasdesigned to drive traffic to a retailer.

In 2005, “the earth moved.” There were search wars, community sites, user-generated content, Web 2.0. Newspapers and magazines responded with premium, branded sites online based on advertising or subscription models.

Book publishers are confused. Search engines treat digitized book content like “free” content. Rights and permissions are unclear. Books are not online — except illegally! Book archives are not digitized.

Before 2004, “book search” took place in a book store.

What is the role of the publisher in a digital world?
What is the right digital strategy?
What are the right capabilities?
“Search” provides new opportunities for publishers.
Publishers must transition from paper to digital.
How can publishers create value and not destroy it?

Some statistics:

  • 65M in the U.S. read more than 6 books a year.
  • 10M read more than 50 books a year. [ed.: waves]
  • Younger consumers read less; they spend more time online

Search is used more often than email.

HarperCollins decided to focus on connecting with customers, rather than e-commerce. Amazon and others already do e-commerce. They focused on the idea of a “digital warehouse” that is analogous to the existing physical warehouse. They want to:

  • promote and market to the digital consumer.
  • use digitized books to create a new publishing/distribution chain
  • protect author’s copyright
  • “replicate in digital world what we do in physical world”
  • got publicity, strong public response
  • no single vendor who could deliver turnkey

Improvements from digital production and workflow could fund some or all of the digital warehouse investment. Projects that were low priority “IT and production” projects become high priority. Savings were realized in typesetting/design costs, digital workflow, and digital asset management.

The digital warehouse now has 12,000 titles. (Looks as though they were scanned, which doesn’t meet *my* definition of “digital content.”)

At this point in the presentation, we began to hear a lot about “control.” Control of content, controlling distribution, and so on.

HarperCollins does not want others to replicate their 9-billion page archive in multiple locations. They want others to link into their digital warehouse. But if storage is cheap and getting cheaper, what’s in it for, say, Google?

Strategic issues for book publishers

  • Should publishers digitize, organize, and own the exclusive digital copy of their book content?
  • Should publisher control the consumer experience on the web?
  • If the cost of 1 and 2 is zero, should every publisher do them both? would they?
  • How to make money

The focus on controlling content was interesting and perhaps not unexpected. The business case based on savings in digital production was also interesting.

Sarah O'Keefe
June 19, 2007
Read More
Industry insights

WritersUA: My sessions

I delivered a session on Coping with the XML Paradigm Shift, in which I introduced my Taxonomy of Problem Writers for the first time. The slides are available in PDF format, and I welcome any and all comments. You probably won’t be surprised that the presentation is slightly over the top. It has, however, already served as a great conversation starter —
I heard people talking about Technosaurs and One-Trick Ponies.

On Tuesday afternoon, I did a double-length, hands-on Introduction to DITA session. (Many thanks to XMetaL for providing attendees with evaluation copies to use during the session.)

I arrived in the room about half an hour before the session and found a few people already moved in. (Always a good sign.) Trying to install and configure software just minutes before a session like this is a truly terrifying undertaking. And as we got closer to the session time, more
and more (and MORE) people kept coming. By my count, we had at least 35 people with laptops and five more without. (That’s about triple the number I’d normally allow in a hands-on training session.)

There were a few kinks, but we managed to get everyone up and running*, and I think the session was valuable. At the end, I polled the room on whether they were more or less likely to implement DITA and got an even split. Perfect!

We will be extending this three-hour session into a two-day Introduction to DITA class, which we expect to begin offering in mid-summer. Watch this space for more details.

* One person had a Mac, which I hadn’t anticipated. Sorry! The two people running Vista also had some issues. There were a few installation errors, but their software seemed to run OK.

Sarah O'Keefe
March 28, 2007
Read More
Industry insights

WritersUA: Pundit panel

The opening session with the ever-popular pundit panel was interesting. Bernard Ashwanden of Bright Path stole the show with a strip routine. Perhaps I should explain.

Bernard pointed out that life was about content, and the tools were just layers on top of the content. To illustrate the point, he took off his vendor shirt, revealing another vendor’s shirt. Then, he took off the second shirt to reveal yet another vendor’s shirt. After five shirts, he ended up with a MadCap T-shirt. I’m going to assume that this was related to shirt size and not some sort of message about who is closest to his heart. I should stress that Bernard did keep his last shirt on.

Although predictions were created independently by the various pundits, they were in substantive agreement in many cases. Everyone felt that the cliched web 2.0 will have a significant effect on technical writers. In a world where end users contribute to product information on wikis, user forums, podcasts, or videos, what is the role of the “corporate” technical writer?

Several people predicted a demise for traditional help authoring tools. They said that tools must evolve to support new media and community publishing models. I agree in part, but I don’t think this will happen in the next three years, as at least one panelist predicted.

As consultants, it’s our job to understand new technology and to be ready to implement it for our customers. But our customers are at different points on the technology adoption curve. We have:

  • Early adopters, who want the latest and greatest technology.
  • Cautious middle adopters, who want to implement proven technology.
  • Late adopters, who are the last ones to move into a new workflow.

As a result, at any given point, our active customers are:

  • Implementing the latest thing
  • Implementing the low-risk thing (which was likely the Next Big Thing five years ago)
  • Implementing the industry standard (which is robust, but not very cutting edge)

The web 2.0 technologies are still on the extreme bleeding edge. A few companies are implementing them (the Quadralay wiki comes to mind), but corporate adoption is going to take years. Furthermore, user-generated content presents enormous logistical, legal, and corporate positioning challenges, which will slow adoption for risk-averse companies (which is most of them).

Sarah O'Keefe
March 28, 2007
Read More
Industry insights

WritersUA: Overview

Attendance seemed to be up a little from last year with approximately 450 people at the show.

Great energy as usual, people were excited to be at the venue.

I got a chance to catch up with many of the Usual Suspects including Char James-Tanny, Alan Houser, Neil Perlin, Paul O’Rear, Dave Gash, Brian Walker, Tony Self, and many others. (If I left you out, it’s because my brain has turned to mush.)

Our booth was extremely busy, and we had great conversations with many attendees. In past years, we would tell people what we do (“XML blah blah structured authoring blah blah FrameMaker blah blah training consulting blah blah”), and some percentage would respond with, “Oh, I use [some help authoring tool] and I don’t need that stuff.” This year, there were two types of responses:

  • “We’re working on an XML implementation.”
  • “We’re thinking about XML.”

The percentage of attendees who do not need to care about XML was extremely low.

Our “Yellow Thingies” were very popular — in addition to chocolate (of course), we were giving away a printed, bound version of three of our white papers (with a yellow cover). You can get the white papers through our online store (free with registration), but attendees really seemed to appreciate the printed version.

Sarah O'Keefe
March 28, 2007
Read More
Industry insights

WritersUA: Rumors

From Char James-Tanny’s helpstuff blog:

Speaking of new features…RoboHelp will support both Windows Vista and Office 2007 in their next release, due out before the end of the year. I also heard today that Frame 8 will go to beta sometime in the next several months, and that a new product (kinda-sorta similar to RoboHelp for Frame) is under development. No news yet on the feature set, but that’s OK…I can wait until it’s released. (Given that I don’t use Frame, I obviously won’t be a beta tester!)

As you probably know, Scriptorium has a long-standing relationship with Adobe. We are an Adobe Authorized Training Center and have also done work for Adobe as a vendor (writing white papers and the like). As a result, we often have pre-release access to software under non-disclosure agreements.

This can make life quite difficult when people ask us about Adobe’s future plans. We aren’t allowed to say anything! You’ll notice, however, that it is possible to get information. My advice? If you want to know about upcoming features, corner the right Adobe person (don’t bug the RoboHelp guy about FrameMaker and vice versa), in private, and ask nicely.

Sarah O'Keefe
March 28, 2007
Read More
Industry insights

Pod people and RoboHelp

The RoboHelp reviews keep coming, and they’re getting ugly. DMN Communications says in their podcast that the new release of RoboHelp shows “almost contempt” for RoboHelp users (approximately 12:30 into the podcast).

On a more constructive note, the podcasters speculate about the lack of integration of RoboHelp with FrameMaker. They point out that RoboHelp’s competitor, Flare, imports native FrameMaker files, whereas RoboHelp requires use of the intermediate MIF (Maker Interchange Format) files. One of the speakers then muses, “Does Adobe’s agreement with Quadralay [to include WebWorks Publisher Standard Edition in the box with FrameMaker] preclude them from integrating RoboHelp?” (11:40)

I don’t know the answer to this question. Random guesses are so much more fun than the generally mundane truth (whatever that might be).

Sarah O'Keefe
February 12, 2007
Read More
Industry insights

Notorious

There’s no such thing as bad publicity, or so the saying goes.

But RoboHelp is trying.

MonkeyPi weighs in with his, er, unique style. In a lengthy discussion of a recent Adobe webinar on RoboHelp, he says this:

But the kicker comes when [Adobe product evangelist] Jacquez says, “…the closest [online help tool] to RH is Microsoft’s HTML Help Workshop.” The clear implication is that RoboHelp is teh awesome, and teh other toolz are teh suxors. Why even Micro$oft’s crappy free tool places higher then our pathetic competitors!!

Adobe says that their competitors’ claims were misleading:

Jacquez says, “…competitors telling people that [RH] is dead… one has to wonder what the competition is going to say when their customers begin to return their product because they bought it under the pretense that RH was dead.”

Let’s get something very clear here. After Macromedia bought eHelp, they killed RoboHelp. RoboHelp was dead — Macromedia was interested in RoboDemo (now Captivate) and not in any other component of eHelp’s product line. So, they laid off most of the RoboHelp team.

Enter MadCap. Many of the ex-RoboHelp people thought that there was still a market for a help authoring tool, so they formed the new MadCap Software and built Flare. And much of Flare’s marketing was based on the idea that 1) RoboHelp is not going to have any updates and 2) Flare is the natural successor to RoboHelp.

Fine. But then Adobe bought Macromedia. And Adobe does have a significant presence in the technical writing market, so suddenly the strategy changes. Adobe decides to resurrect RoboHelp.

All of this makes perfect sense. And there’s nothing particularly nefarious about what happened. RoboHelp didn’t make sense in Macromedia’s web-heavy product line-up. RoboHelp can make sense for Adobe, especially if they market RoboHelp, Captivate, Acrobat, and FrameMaker as a core set of technical writing tools, along with Photoshop, Illustrator, DreamWeaver, Flash, Acrobat 3D, and others for more specialized requirements. You can see some of this positioning beginning to happening in the Adobe webinar.

Meanwhile, though, response to RoboHelp 6 has been, at best, mixed. One day after MonkeyPi’s dissection of the webinar, we have 10 Reasons Not to Upgrade to RoboHelp 6 at I’d Rather Be Writing. They include the following (read Tom’s blog for an explanation of each item):

1. Communication from Adobe is bleak.
4. Not compatible with Word 2007.
5. Requires at least 15 macros to clean up [print] output
9. Interface is 1996.
10. Its apparent ease of use is only because you’ve been using it for 10 years.

The writer seems particular offended by Adobe’s lack of response to questions and comments during the webinar and on their new TechComm blog:

[…] Adobe’s RoboHelp blogger either is totally clueless about responding to comments, or he doesn’t understand that a blog is not a PR marketing vehicle. […] Sorry Adobe, but you really get a D when it comes to communication.

This is interesting. Five years ago this would have been a non-issue — obviously Adobe gets to control the content of marketing communications on their web site. No more.

As I use RoboHelp about once every five years, I don’t really have an opinion on the merits of the tool. But I am watching the blog-kerfluffle with some interest, especially as I wonder what reaction to FrameMaker will look like, when they release their next version, probably in mid-2007 (according to public statements from RJ Jacquez).

Sarah O'Keefe
February 7, 2007
Read More
Industry insights

VC pitch template

This week, I attended the Southeast Venture conference, held at the new Umstead Hotel in Cary, North Carolina. The conference was only about two miles from our office and the opportunity to see this brand-new, five-star aspiring hotel was too good to pass up. (Hard to justify staying there when home is less than 20 minutes away…)

The conference included a series of 10-minute pitches from various companies looking for funding.

After seeing a couple dozen of these sessions, I have put together a helpful template for anyone looking to do a demo pitch.

First, be sure to use the following phrases:

  • “addressable market is over $X billion”
  • “unique value proposition”
  • “sustainable advantage”
  • “barriers to entry”
  • “strong intellectual property assets”

Then, you’ll need two charts. The first one shows revenue and looks like this:
Revenue from 0 today to $50 million at some future date
The second one shows profits and looks like this:
Profits currently zero, drop to negative, then increase to $50 million at some future date
So. Hockey stick and check mark. It’s all very simple.

Sarah O'Keefe
February 2, 2007
Read More
Industry insights

An example of good technical writing

Not too long ago, I took a quick look at XMLMind XML Editor (XXE). I downloaded and installed the software, dropped in a couple of existing XML files, and tried to create some new content.

I didn’t like it. Couldn’t get it to do what I wanted.

This week, I ran across Antonio DaSilva’s article about XXE (hi, Tony!). I read the article, then opened up my copy of XXE (still installed). And suddenly, the product worked just fine.

XXE isn’t my favorite XML editor, for the price, it’s a great tool. (The standard edition that I’m using is free.)

There were a couple of bits of information in the article that really helped me. I think the key insight that Tony provided for me was that XXE does not permit your content to be invalid. Thus, if you try to paste an element into an invalid location, the paste action is blocked. I don’t like it, but at least now I understand why the software is behaving the way it does.

Many thanks to Tony for a great article.

Sarah O'Keefe
January 24, 2007
Read More
Industry insights

Anonymous blogging has its benefits

monkeyPi posts a review of RoboHelp 6.

Warning: May be hazardous to keyboards.

RoboHelp 6 finally arrives, and it’s craptastic at monkeyPi

I haven’t looked at RoboHelp in years, so I have no idea whether his issues are valid or not.

[I have this feeling that I know the monkey behind monkeyPi, but I’m not totally sure. Meanwhile, I will continue my demure, unanonymous blogging here.]

I did notice a couple of things about the RoboHelp release. First, based on the feature set, Adobe has clearly decided that XML is not a priority for RoboHelp users. This is in contrast to MadCap Flare, which touts their tool as being “XML-based” at every opportunity. Second, the press release announcing RoboHelp 6 has a quote from the former eHelp VP of Engineering, who is now with an unrelated company (Unwired Software). A lot of MadCap’s marketing effort is built around their identity:

“MadCap Software is just a new name for a group of familiar faces that have been leading the technical writing community for over a decade. MadCap is home to some of the most experienced software architects and product experts in the industry, including many former core members of eHelp Corporation, creators of RoboHelp.”

One gets the impression that Adobe has been paying attention to Flare’s marketing, and that Adobe marketing is just a tad ticked off.

Sarah O'Keefe
January 17, 2007
Read More
Industry insights

XML 2006: Not the takeaway I was expecting

A conference presentation is a specialized form of technical communication — in addition to basic technical writing skills, a presenter needs the ability communicate effectively in a conference session. The presenters here are technical experts, but many of them are really terrible at the front of a room!

For example, they are making the following mistakes (some presenters are doing all of these):

  • Reading slides
  • Slides with too much text in too small a font (the vast majority of the presentations)
  • Mumbling
  • Poor microphone management (not talking into the microphone, moving back and forth so that the volume goes up and down)
  • Poor time management — spending too much time on introductory material and not enough time on the important bits of the presentation
  • Speaking in extreme monotones
  • Sentences trailing off in volume

I don’t know exactly how conference proposals were evaluated, but it looks very much as though content is king (sounds good, right?) Proposals were evaluated on technical merit and little or no consideration was given to presentation skills.

Unfortunately, this doesn’t work. If you have great knowledge, but are unable to communicate that verbally, then putting you at the front of a room full of people is not helpful.

And worst of all, there are NO EVALUATIONS! That means that there’s little or no chance that the situation will be addressed next year. (There is an overall conference evaluation form, but you have to remember to go get it at the registration desk.)

Joe Welinske of WritersUA does the best of job of speaker assessment I’ve seen:

  • He asks participants to fill out evaluations for each speaker. There are just a few questions, and each evaluation is an entry for a door prize. In other words, he bribes participants to fill out the evaluations.
  • Speakers who suck with poor evaluations aren’t invited back the next year.
  • He rarely allows panels or group presentations (too much diffusion of responsibility).
  • Speakers who were rated highly in the past get stars on their bios, so attendees have some additional information to help them choose a session.
  • Joe attends many conferences each year to evaluate prospective speakers and to gauge which topics are getting the most interest from attendees. He builds his program based on this research.

The contrast between the presentation quality here and at WritersUA is really quite stunning.

Sarah O'Keefe
December 6, 2006
Read More
Industry insights

XML 2006: Content Management APIs

How Google and wireless access have changed the world: I’m sitting in this session, and the presenter’s approach isn’t working for me. So, I google jsr 170 and I find this article at CMS Watch that explains it quite nicely.

Having skimmed that, I return my attention to the presenter, and find that he’s making a lot more sense.

The CMS Watch article has an excellent definition of JSR 170:

JSR-170 promises the Java world, and possibly beyond, a unified API that allows accessing any compliant repository in a vendor- or implementation-neutral fashion, leading to the kind of clean separation of concerns that characterizes modern IT architectures. Some people call JSR-170 the “JDBC [Java Database Connectivity] of Content Repositories.”

Now, we have Michael Wechner presenting on what is theoretically the same topic. Only not. He leads with this: “Today, every CMS is producing its own user interface, which is just kind of silly.” And then this analogy: mail servers are standardized, but you’re free to use your own client/front end. Similarly, CMSes need a common backend and you can do whatever on the front end.

I feel smarter already.

Wechner’s company, Wyona, is an integrator for open source CMS.

He points out that the ability to work offline is important because people aren’t always online. He uses the example of a train ride in Europe — the obvious equivalent in the United States is airplanes. (Side note: If people are permitted to yap on their cell phones in-flight, I’m probably going to stop traveling altogether. It’s bad enough on the ground at the gate.)

OK, and I think he’s proposing that you use existing protocols, such as Atom and WebDAV, to do CMS connections.

Sarah O'Keefe
December 6, 2006
Read More
Industry insights

XML 2006: XML in Legislation

Timothy Arnold-Moore of SAIC (I think). Good presenter with a sense of humor.

Magna CartaHe points out again that legislation has a shelf life of hundreds of years and so a typical word processing format, which lasts about 10 years, is really not an option. Look! A picture of the Magna Carta to illustrate his point. Bonus points for use of graphics. Even if he did (as I just did) pull it from Wikipedia.

Best practices for legislation:

  • Updates are made to bills from the floor of the legislative chamber and are thus near-instant.
  • Provide information about bill status, proposed amendments, consolidated form of amendments
  • Provide the “as made” versions as soon as enacted
  • Consolidate amendments unofficially. Side note: The US Code takes more than two years for official updates. (ed: That is pathetic.)

Working with legislative XML requires some heavy lifting in revision tracking. Interesting. They have the proposed act in one document and a separate Change Description Document. They integrate the two to produce the amended version(s).

Nice demo of the Tasmanian EnAct system. This presenter is familiar with the concept of “show, don’t tell.” They use an SAIC product, TeraText, as the foundation.

Sarah O'Keefe
December 6, 2006
Read More