Tech writers in the media

Sarah O'Keefe / NewsLeave a Comment

I was listening with half an ear to NPR’s Weekend Edition when the puzzler segment came on. During the interview, we hear that the winner, Judy from Lexington, Mass., “leads a group of technical writers at Sybase.” After that, they had my undivided attention as Judy made her way through a tricky set of questions.

I’ve always thought that technical writers and other professional word people should be good at these puzzles. This is the first time I’ve heard a player identified as a technical writer.

The phone ate my homework

Sarah O'Keefe / Conferences1 Comment

At the STC conference, I used my handy camera phone to take a picture of Adobe’s FrameMaker booth, complete with FrameMaker product manager. I planned to post that picture here.

[envision the lovely FrameMaker booth with Adobe representation]

Unfortunately, the phone ate the picture. You’ll have to take my word for the following:

  • Adobe was represented at the STC conference.
  • The booth had FrameMaker signage.
  • The FrameMaker product manager was present in the booth.

I also ran into numerous friends and colleagues, including:

  • Dieter Gust and Michael Plattner of ITL (German page, English page). Among other things, they have been organizing FrameMaker user conferences in Germany for the past decade or so.
  • Paula Berger, the incoming Second Vice President of STC. Paula was last seen running into a session because she was late. And on the panel. Paula should be a contestant on Overcommitted Idol.
  • Nick Rosenthal of Salford Translations, who is more fun to hang around with than anyone in the localization business should be.
  • Joe Welinske, who was likely scouting for next year’s crop of presenters.
  • Folks I would loosely characterize as Fellow Consultants: Alan Houser, Neil Perlin, Kit Brown, Dave Kmiec, and others.
  • I ran into a surprising number of North Carolina-based folks, which led to some major cognitive dissonance. But thanks for sharing your umbrella, Greg!
  • People I have Trained: Donna C., Justin B., and others
  • People Who Wanted to Ask Me Questions
  • Apologies to anyone I missed. It was a crazy couple of days.

XML-based authoring versus structured authoring

Sarah O'Keefe / OpinionLeave a Comment has an interview with Mike Hamilton, formerly of Macromedia/eHelp/Blue Sky, now with MadCap Software.

The interview includes some information about Flare, the RoboHelp replacement tool that MadCap is developing. Flare is billed as an XML-based authoring tool. Mike Hamilton describes the competitive landscape like this:

There are a lot of XML tools and workflows out there, but they either fall into the “you better really know what you’re doing” camp of editors designed for programmers or they fall into the enterprise camp where it takes a lot of resources to set up a system, create custom/proprietary transforms, maintain the system, etc. Many small to medium sized companies don’t have the in-house expertise to build and maintain such systems. MadCap Flare is designed to fill that gap in between. Will MadCap Flare create XML files – yes, but the author doesn’t have to even realize this. Will MadCap Flare provide transforms to repurpose this XML content into other useful formats – yes, but the author doesn’t need to know what the term transform means, let alone have to know how to write one. MadCap Flare will be an affordable, shrink-wrap, turn-key solution.

Thus, we have a Goldilocks approach to XML tools: too small (for programmers and XML data), too big (scary enterprise tools), and just right (Flare). This misses a critical distinction. XML is a file format that provides a vendor-neutral way of exchanging content. In addition, XML’s file format supports structured authoring, in which you define a set of rules for your document and then enforce them. If you want to implement structured authoring for your organization, your authoring tool must support the definition and enforcement of your document rules. This is usually done with a document type definition (DTD) or schema file.

To provide structured authoring support, a tool needs the at least the following basic features:

  • Lets you create structure rules
  • Enforces structure rules in your documents (validation)
  • Lets you define and supply metadata for the document components

Flare will provide XML support, which means that it should be relatively easy to extract information from Flare for repurposing elsewhere. But I haven’t seen anything that indicates that Flare will support structured authoring.

For more on structured authoring, see our XML and Structured Authoring white paper (free, but registration required)

(Interview found at Keith Soltys’ Core Dump)

DocFrame case study

Sarah O'Keefe / ConferencesLeave a Comment

At the STC conference in Seattle, there was a case study session on our DocFrame solution delivered by Vici Koster-Lenhardt of Coca-Cola and Michael Plattner of ITL.

A PowerPoint file with their slides is available here.

If you’re considering structure implementation, and want to do it fast, this is worth a look.

Nobody likes product activation…

Sarah O'Keefe / OpinionLeave a Comment

But then you read stuff like this recent gem on the wwp-users list:

Date: Mon, 09 May 2005 17:06:02 -0000
Subject: Help!!!
Hello everybody,
I signed in this gropu 1 month ago because I needed to do my report
intership about framemaker and webworks.
Obviously I cant buy the software because it is very expensive for me
and I only need the software for three months.
Anybody of you know if I could get an special license or a demo
version for three months??
I tried to download from the internet but the crack didnt work, so I
would appreciate if somebody could help me.

That makes it hard to argue with activation, which would probably deter the casual piracy described here. Ed Foster has more on Adobe’s decision to add activation in his GripeLog.

Free the Chapter!

Sarah O'Keefe / OpinionLeave a Comment

Sean McGrath argues that the separation of content into files and directories is an artificial one that should go away. – Books/chapters and directories/files – dichotomies considered harmful

Imagine a world in which the file system explorer is the top level application. It manages a single, humungous file on the disk into which you embed documents, spreadsheets, databases etc. Each thin[g] you embed into the explorer can itself embed other things to any depth required.

In such a world, directories/files have merged into one abstraction. The book author does not have to introduce artificial segmentation of the book into separate entities. In such a world, filenames become something of an oddity. What do you need filenames for? You would only really need a filename at the point where you decided to exchange information between systems A and B.

It’s possible to split a book into meaningless chunks; for example, by requiring each file to contain ten pages. The result would be book chunks that have no semantic meaning. But a chapter is more than just a handy place to split your book into files. Chapters are semantic units. They also, by convention, start at the top of a page and often have stand-alone numbering schemes (5-1, 5-2, 5-3, …) to provide visual separation that supports the semantic meaning. That makes the chapter more than just an artificial segmentation.

Atlas Shrugged

Sarah O'Keefe / NewsLeave a Comment

With apologies to all, I simply can’t stop myself from using that title.

Quadralay has released their latest incarnation of WebWorks Publisher, now called ePublisher Pro. While under development, the product was code-named Atlas.

Press release

In the FrameMaker details section, you find this:

IntelliStyles […] automatically imports your FrameMaker styles into your WebWorks ePublisher Pro project, establishing a more advanced starting point for your project and saving you time and effort. Based on your project’s native styles, you can use ePublisher Pro’s new Style Designer to develop all of your manual style-based customizations, such as designating paragraph styles as TOC entries, generating page splits, and including special features – drop-down text, breadcrumbs, Related Topics, and more.

This may be good news for fans of the short-lived RoboHelp for FrameMaker from eHelpMacromediaAdobe. It looks as though Quadralay has added many of the features that RHFM users liked best.

Although The Product Formerly Code-Named Atlas has its roots as a FrameMaker converter, Quadralay’s web site indicates that the Word version will be released first.

Word details

The macro language that we all know and, er, love has been replaced with XSL-based processing.