Palimpsest

Webcast: Trends in technical communication, 2012

February 1st, 2012 by Sarah O'Keefe

In this webcast recording, Sarah O’Keefe and guest presenter Char James-Tanny discuss tech comm trends for the upcoming year and beyond.



“Trust me” isn’t a business plan

January 30th, 2012 by Alan Pringle

Knowing you can rely on someone is vital to professional relationships. But when it comes to proposing process change, the words “trust me” are never, ever enough.

For those of us in technical communication, process change often involves selecting new tools and technologies to make creating and distributing content more efficient. If you want to propose changes to your content processes, you need some compelling numbers to back up what you’re suggesting.

Don’t assume that your positive relationships with coworkers and management will guarantee a warm reception to your ideas. Yes, those relationships can help you get your foot in the door to introduce your ideas, but proposing changes without a solid business case can quickly tarnish good relationships. People don’t like having their time wasted—even by good intentions.

Photo of human pyramid

Flickr/notsogoodphotography

Boost your chances of having your proposal heard and considered by doing some research. Provide answers to tough questions such as:

  • How much time and money will be saved by the content reuse enabled by the new system?
  • What kind of savings will be achieved in automating formatting for the source language and localized content?
  • How long will it take to recoup the cost of the new system?

Even if your proposal is shot down or put on hold because of corporate belt tightening, developing a strong business case demonstrates you have an understanding of your workplace that reaches beyond writing content. That kind of analytical thinking benefits your employer and—more importantly—your career.

Trust me!



Another peril in ebook publishing: Amazon KF8 compatibility

January 24th, 2012 by Alan Pringle

KF8. Nope, it’s not K2‘s long-lost mountain cousin. It’s Amazon’s new ebook format.

While dealing with this new format probably isn’t as daunting as scaling a 28,251 ft. mountain, KF8 is providing a particularly bothersome challenge right out of the gate: it’s not compatible with any Kindle devices other than the Kindle Fire!

Scriptorium Press has already released Kindle editions of Technical Writing 101 and The DITA Style Guide in the AZW format, which is basically a highly compressed MOBI file. Because we have published books in the older format and because I own an e-ink Kindle model that predates the Kindle Fire by a few months, I immediately wanted to know which devices could handle the new KF8 format.

While researching compatibility, I noticed how Amazon’s carefully worded overview of KF8 attempts to skirt the issue: “Kindle Fire is the first Kindle device to support KF8 – in the coming months we will roll out KF8 to our latest generation Kindle e-ink devices as well as our free Kindle reading apps.”

 Still from The Perils of Pauline (1947)

Still from The Perils of Pauline (1947)

This fancy footwork wasn’t lost on writer Guido Henkel, either, who pointed out:

One of the issues that truly and really disturbs me is the lack of support on anything but the Kindle Fire. Although Amazon had initially announced that the current generation Kindles and software readers would be KF8 capable, that statement was simply not true. It has since been revised that these devices will support KF8 some time in the future. In the real world that is a big difference.

In a blog post yesterday, Sarah O’Keefe pointed out how the release of Apple iBooks Author is contributing to the growing pains in the digital publishing industry. The release of KF8 is adding to those pains as well. In fact, Amazon has compounded the challenges by releasing a format that currently doesn’t work across its own Kindle family. I hope Amazon resolves questions about backward compatibility very soon. (Are firmware updates for e-ink models on the horizon, perhaps?)

Like Sarah, I have doubts that the big ebook distributors will graciously adopt a standard such as EPUB to make the lives of both publishers and readers easier. There’s not as much money to be had in adhering to standards. As a result, Scriptorium Press and other publishers will have to figure out how to keep their source content in a neutral(ish?) format that is easily converted to the ebook formats the distributors require. (By the way, we keep our source files in DITA. We transform the files into EPUB, which we sell, and we also use Amazon’s free KindleGen tool to convert the EPUB into the Kindle format.)

Stay tuned for another installment in The Perils of Ebook Publishing! I suspect there are many, many installments to come.

Thanks to Keith Soltys, whose blog got me thinking about KF8 and its impact.



The dawn of digital publishing

January 23rd, 2012 by Sarah O'Keefe

Is a week long enough to gain some perspective on the new landscape in ebook publishing?

If 2010 was the Year of the Many Datasheets, 2012 is looking like the Year of the EBook. We are getting numerous inquiries about how to change publishing processes to accommodate the new requirement to deliver content for EPUB and Kindle. (The Year of the Process Change Driven by New Digital Requirements may be more accurate, but it just doesn’t flow trippingly off the tongue.)

There’s been plenty of technical discussion on other sites of the major new developments: the new Kindle format, the new Apple toolset, and, especially, the licensing restrictions attached to Apple’s new iBooks Author.

[Update: A discussion of the technical problems and why it matters from ZDNet]

Cave painting, Algeria

The artist was probably criticized for the monochromatic palette.

These are all valid issues, but they miss the larger point. We are at the dawn of digital publishing. We have a long way to go before we master our new medium.

Like the cave painters, we face enormous technical challenges (them: creating a color palette; us: creating valid EPUB or Kindle formats), archival issues (them: humidity and cracking stone; us: evolving incompatible formats), and new frontiers (them: mastering the illusion of perspective; us: employing effective 3D images).

iBooks Author provides an interesting sandbox for experimentation for publishing professionals, but no more. The current iBooks Author license only allows you to sell through the iBooks store if you develop in iBooks Author. In addition to this silly limitation, the ebook file produced by iBooks Author is not a valid EPUB; the code is full of proprietary extensions.

So what was Apple thinking when they released a beautiful, free MacOS-only application that produces ebooks for iBooks only?

This is about Amazon.

Apple is strong in education and design. Amazon’s Kindle format is doing well in ebooks and particularly cheap, self-published ebooks. Apple, as usual, is going after the high-end, high-margin market: textbooks.

They are attempting to tie up the following:

  1. iPad as a consumption device for textbooks.
  2. iBooks Author to create textbooks.
  3. iBooks Store as the textbook marketplace

“But why would a publisher agree to this? We have to publish to lots of different formats.”

Close-up of Sistine Chapel fresco

Detail from the Sistine Chapel

The publishers are not the target audience for this new approach. The target audience is textbook authors—educators who already live in a MacOS/iPad universe and have no interest in other technologies. Apple’s intent is to eliminate publishers from the equation and pick up those teachers or professors who want to create one textbook for their particular area of expertise. Apple is providing tools that are simple enough for a non-professional content publisher, and that could create high-quality results. (I’m reminded of the release of PageMaker 1.0, which was also quite limited but at the same time revolutionary.)

The negative coverage of the technical details misses the point. Apple is attempting to disrupt the textbook market by:

  • Providing software for content creation that will be compelling to the average textbook author.
  • Providing a venue for distributing content that will be compelling to the average textbook author.
  • Providing a way to produce digital content that will be compelling to the textbook user.

Apple will probably eliminate the licensing restriction within a few months—the format being created won’t render properly in other ebook readers anyway. Don’t expect them to conform too closely to the EPUB specification, though. Making an incompatible format is a competitive advantage.

Will it work? I refer you to the great Browser Wars of yesteryear for a historical (!) context. Back then, the open source movement wasn’t as strong as it is today, though.

I await new developments from Amazon.

What are your thoughts?



Webcast: Content strategy in technical communication

January 20th, 2012 by Sarah O'Keefe

In this webcast recording, Sarah O’Keefe explores how to develop a content strategy specifically for technical content. That means stepping back from the temptation to focus on tools and instead taking a hard look at what the users need and how best to deliver it.



Tempus fugit

January 17th, 2012 by Sarah O'Keefe

I’ve been thinking about how time affects communication. We have constant deadlines, some of which are easier to meet than others. But there are other ways in which time affects content strategy.

Language usage evolves

Today, I can write:

Like the Euro, this [anything] is in deep crisis.

I am confident that my readers will understand the analogy. But ten years from now, the Euro may be back on track (or gone). A reader in 2022 must then recognize that this sentence was written in 2012 to put it in the proper context. It’s likely (unfortunately) that the Euro events will be remembered in 10 years, but what about something like this from Twitter:

@lizzwinstead I would like to see the answer translated into the Kardashian unit of time measurement.

— Melissa (@jamrockstar) January 9, 2012

We use pop culture references because they are entertaining, but they are also obstacles to content longevity.

Language evolves

Language changes over time, and our word choice, even without obvious pop culture references, ties our text to a temporal frame of reference. Take, for example, the word “provisioning.” (Yes, it’s a horrible word. Sorry.)

My most recent encounter with “provisioning” was in the context of digital magazine publishing. My mental model is now that provisioning refers to the process of supplying a user with magazine content based on her subscription status and/or one-off purchases. However, I had trouble finding examples of this definition. For example, Wordnik’s examples for provisioning are mostly in telecommunications and finance:

“It is hard to envisage duct access providing both Carphone and Sky with even half of their long-term provisioning requirements.”
Latest financial, market & economic news and analysis | guardian.co.uk

[...]

“BBVA said it had to set aside an extra € 198 million as a result of the change in provisioning rules.”
The Wall Street Journal: Financial Briefing Book: Oct. 28

But scroll down the page to the Twitter examples, and you see something different:

das iOS Provisioning Portal darf ruhig mal von einem apple usibility team unter die lupe genommen werden.”
@nordpixel

“Guh, somehow Xcode nuked all my provisioning profiles.”
@jstr

“Блин, в iTunes Connect черт ногу сломит – уже минут 40 пытаюсь вспомнить где находится управление provisioning профилями. Безрезультатно.”
@KirkFawkes

Here, the usage for “provisioning” is all about telecommunications and a little bit of iOS.

From there, I backtracked to Wikipedia:

In telecommunicationprovisioning is the process of preparing and equipping a network to allow it to provide (new) services to its users. In NS/EP telecommunications services,“provisioning” equates to “initiation” and includes altering the state of an existing priority service or capability.[1]

There is also a reference to mobile content provisioning later in the article, but this turns out to be quite a different definition from what I expected:

This refers to delivering mobile content, such as mobile internet to a mobile phone, agnostic of the features of said device.

Finally, I consulted the Oxford English Dictionary:

The supplying, stocking up, or making of provisions; the action of provision v.
1787    A. Hawkins tr. V. Mignot Hist. Turkish Empire I. 306   His opposition in the council to the provisioning of Rhodes [Fr. le conseil à ce que Rhodes fût approvisionnée] when war was not yet declared‥had raised suspicions.
None of the OED examples are related to technology; instead, they reflect the military usage where this word originated.
I conclude that “provisioning” for digital content is a new usage of the term, which means that I probably need to explain it in any content that I’m creating. And that brings me to a third issue.

The reader evolves

In the early days of graphical user interfaces, it was quite common to include basic information about mouse operation in technical documentation manuals. When was the last time you saw something like this in technical content?

http://tech.tln.lib.mi.us/tutor/intro4.htm

The baseline assumptions we make about audience knowledge have changed. Knowledge that starts out as highly specialized (like my unorthodox definition of “provisioning”) may, over time, become general knowledge. Consider the evolution from “smartphone application” to “mobile application” to “mobile app” to just “app.”

This implies that we can, over time, remove information from our content. Phone companies do not explain the concept of an area code. Actually, it’s worse than that. AT&T’s instructions do provide a link in case you don’t know what an area code is:

Let’s assume you need further explanation of “the area code” above. This is what you get:

Uh, thanks? I don’t think this is going to help someone who doesn’t know what an area code is. So, I did what we all do and tried a Google search for “what is an area code?” and got this at position #3, from WiseGeek:

An area code is a section of a telephone number which denotes the broad area that the phone receiving the call is based in. The area code is the section just before the local number, and just after both the access and country codes. An area code usually doesn’t need to be dialed if the number being called is in the same area as the number making the call, unlike the local number, which must always be dialed in its entirety.

In the United States, an area code is a three digit number that comes before the seven digits that make up the local number, three for the prefix and four for the suffix. While the prefix of the local number gives an idea of the more specific area, such as town or neighborhood, the areacode denotes the larger region, either a whole segment of a city, or even an entire county of part of a state.

Once again, unofficial third-party content wins. But I digress. The point, as always, is that you need to know your audience. The category of “people who don’t know what an area code is” do not need a technical discussion of the finer points of area codes. They need a clear explanation of (what we consider) basic phone number concepts.

What information is in our content today that will be irrelevant in a few years because it will have become general knowledge? Can we identify that information ahead of time? How do we plan for information decay?



DITA reporting tools in oXygen

January 12th, 2012 by Sarah O'Keefe

Need some basic metrics on your DITA files? Wondering whether your topics are the right length or not? Check out this new feature in oXygen version 13.

There’s a new DITA Map Metrics report in oXygen v13. It provides information about your map file, the size of the topics, the elements you used, and more.

To run the report, you use a transformation scenario, so you first open the map (and make sure you select the root element of the map or you get a partial report, which was a surprising “feature”), and then select Document > Transformation > Configure Transformation Scenario.

Select the DITA Map Metrics Report and then Transform Now.

An excerpt of the result is shown below:

The report will tell you which elements you are using, the average length of your topics, and much more. It’s extremely useful for evaluating the completeness of a DITA map. For example, if the report shows lots of short topics with only a few words, that would tell you that those topics are probably incomplete. Conveniently, the list of shortest topics is linked to the source files, so you can click on the link and see the file immediately to figure out what to do.

George Bina of oXygen showed me this report at tekom in October. My advice was to charge extra for it, but you’ll be pleased to know that he ignored me and included the report in the regular product.

The report itself is generated by an XSLT file that runs through the DITA Open Toolkit. You could modify the XSLT to create your own custom report or extend what’s there.

I anticipate using this report quite heavily over the next year as I work on a new book.



Drink me: starting small like Alice

January 9th, 2012 by Alan Pringle

“What a curious feeling!” said Alice; “I must be shutting up like a telescope.”

And so it was indeed: she was now only ten inches high, and her face brightened up at the thought that she was now the right size for going though the little door into that lovely garden.

Lewis Carroll in Alice’s Adventures in Wonderland

For many in tech comm, the lovely garden is often an XML-based workflow that enables single sourcing, reuse, and automated formatting. Unfortunately, it can be hard to justify the expense of that garden a new publishing process, particularly if you work for a startup or if you are the lone technical communicator at your company.

That doesn’t mean you should just throw your hands up, even when you’re stuck with tools that are suboptimal. (Microsoft Word, I’m looking at you.)

Instead of focusing on what you don’t have, take a closer look at what you do have. Sure, the authoring tool you’re using may be crapulent, but there are probably some no- or low-cost things you can do to maximize your efficiency while using that tool. In particular, you can develop a template—and then apply it consistently. (Before you say, “Well, duh! Templates are fundamental! Off with his head!”, realize that there are tech pubs departments that don’t have templates or don’t use them consistently. I’ve seen a lot of authoring processes that weren’t nearly as template based as they should have been.)

The immediate benefits of a template are hard to understate:

Sir John Tenniel illustration/Project Gutenberg

Sir John Tenniel illustration/Project Gutenberg

  • Authoring is more efficient because you already have styles to apply to content: no need for time-consuming formatting when you can just apply an existing style.
  • The uniform appearance of content makes it easier for end users to read, and it just looks more professional.

A huge benefit to religiously following a template, however, is not apparent until you move to another authoring tool or an XML-based workflow. Having worked on the conversion processes for thousands of pages of content in my 15 years at Scriptorium, I can tell you with absolute certainty that it is easier (and therefore cheaper) to convert source files based on a well-designed template. On-the-fly formatting and one-off tweaks are the Achilles’ heel/Kryptonite/<insert your own metaphor here> of  smooth, cost-effective conversion processes.

If you are in a situation where it’s currently hard to justify a switch to a new workflow, don’t wistfully look through the door wondering how you’re going to get to the lovely garden of XML (or whatever) on the other side. Instead, ask yourself if you’ve taken steps to make your current workflow efficient and repeatable. Creating and using a template will do just that, and it doesn’t take a tremendous amount of time to develop one—particularly if you have an existing file that you can use as a good starting point.

In the short term, using a template makes working with any tool more tolerable, and it gives your content a consistent look-and-feel that users appreciate. In the long term, template use will minimize bumps when you revamp your workflow.

P.S. Don’t be shy about sharing the short- and long-term benefits of template use with your management. Showing your bosses you’re thinking about the bottom line proves you’re more than “just a writer.”



2012 predictions in technical communication

January 3rd, 2012 by Sarah O'Keefe

It’s time for that annual exercise in humiliation known as the “review of last year’s predictions” followed by the “some people never learn” event in which I soldier on with new predictions.

Here’s last year’s edition. We predicted:

  • A schism in tech comm between “just writers” and technical communicators
  • The age of accountability, where writers are evaluated on metrics
  • An increased focus on business value, where writers must show the value of what they are producing
  • Make-or-break time for authoring tools and a shakeout in the market through mergers and acquisitions

Not too bad, as predictions go. (At least none of them were completely wrong!) We didn’t see any major acquisitions (although I heard a lot of rumors), but I think the the metrics, business value, and increasing separation of “haves” and “have-nots” is fairly accurate. Of course, these predictions were also nicely vague, which makes it a little easier to claim victory.

Merger activity seems to be concentrated in the “translation companies buying CMS vendors” area. I haven’t quite figured that one out, but there it is.

What will 2012 bring to us?

The rise of cloud-based technical communication tools

2012 looks like The Year of Cloud-Based Tech Comm. I mentioned general cloud stuff in the 2010 predictions post, but there wasn’t much DITA or XML support. Today’s tech comm contenders include DocZone and easyDITA for inexpensive web-based DITA CMSes, along with authoring tools such as Xopus. Astoria and Vasont both have cloud solutions. And that’s just the DITA/XML space. In December, Author-it also announced a cloud solution, and I’m sure I’m missing someone.

Not every tech comm group wants or needs a cloud solution, but there is demand for this approach, and I expect that more companies will need to provide a cloud option. The advantages of avoiding server maintenance and desktop installations are compelling to many organizations. The desktop installation is particularly unattractive to IT when there are dozens or hundreds of subject matter experts. Installing an in-house server (for example, a wiki) that allows users to edit in the browser is potentially cost-effective. (We can argue about whether this is a true “cloud” solution.)

Cloud- and/or browser-based solutions eliminate the authoring tool costs—installation, configuration, maintenance, and support. Without per-seat configuration costs associated with desktop tools, organizations can look at opening up authoring and content collaboration to a larger audience. (Note that many cloud solutions do charge per user.)

Notably absent from the cloud list are the help and print publishing vendors.

Convergence with UX driven by mobile requirements

The limited screen real estate on mobile devices makes delivery of user assistance especially challenging. A traditional “webhelp” system is out of the question (the tripane doesn’t fit on the device screen!), and help that takes over the screen requires the user to switch back and forth between the app and the help. A better approach is to embed user assistance directly into the app, and this requires close coordination with development and the user experience (UX) team. Thus, I expect greater overlap and interaction between UX and tech comm, as we try to work out how to share those small screens and where to put user assistance. The traditional approach, where tech comm delivers content that is “dropped into the build” at the last minute, is not going to work for mobile development. For tech comm, this could be an opportunity (work more closely with UX) or a threat (UX just builds their own user assistance; tech comm is cut out of the process).

Divergent strategies for tool vendors

Tool vendors will decide that marketing “true” tech comm is too difficult. Instead, they will cast their lot either with marketing communication or with IT as they attempt to sell into tech comm. As a result, we will see increasing divergence of marketing messages. The marcomm crowd will focus on:

  • Shiny!!
  • Rich media (audio and video components or deliverables)
  • Sophisticated formatting
  • Diverse deliverables (Look! Save as EPUB!!)

The IT crowd will focus on:

  • Automation for cost reduction
  • Automation for faster delivery
  • Automation for accuracy
  • Automation to support accountability and metrics
  • and, dare I say it, AUTOMATION

Interestingly, both strategies are an effort to liberate their tools from the tech comm dungeon.

Our customers demand automation. They may want Shiny in version 2, but they are focusing on automation first. That requirement is pulling them out of proprietary authoring and publishing systems and over to standards-based solutions.



The passion quotient

December 15th, 2011 by Sarah O'Keefe

You’ve never heard of the passion quotient? That’s because I just made it up. For example, if 5 authors report that they use Tool X and it is very important (5 on a scale from 1 to 5), then Tool X scores a perfect 5 PQ.

The formula is this:

PQ = ((# of authors at importance 5 * 5) + (# of authors at importance 4 * 4) + …) / total # of authors

In other words, we are looking for the tool for which the importance is ranked the highest.

Joe Welinske and WritersUA recently published their annual tools survey. In this survey, the PQ winner, by a lot, is MadCap Flare, which scored a 4.60 PQ. Of 225 respondents, 184 gave Flare the Very Important (5) rating.

I am fascinated by the fact that Flare scores so highly, especially compared to other authoring tools (in descending order):

  • Adobe FrameMaker, 3.79
  • Adobe RoboHelp, 3.76
  • Author-it, 3.71

My initial theory was that Flare is an all-in-one tool, so it might get a higher ranking than FrameMaker/RoboHelp (where the votes might be split), but notice that Author-it, which is also an all-in-one solution, has a PQ very similar to FrameMaker/RoboHelp and not to Flare. I await enlightenment from my readers.

Meanwhile, I noticed that oXygen and XMetaL have the same number of responses (67) and scored almost identically on the PQ (3.36 and 3.37, respectively).

So then, I graphed the results by percentage that reported each level of importance.

Tool 5 4 3 2 1
Flare · MadCap Software 81.78% 7.11% 3.56% 4.00% 3.56%
Author-it · Author-it Software 53.42% 9.59% 9.59% 9.59% 17.81%
RoboHelp · Adobe 52.92% 10.00% 11.25% 12.08% 13.75%
Oxygen · SyncroSoft 38.81% 10.45% 16.42% 16.42% 17.91%

For clarity, I omitted FrameMaker, which has numbers very similar to RoboHelp, and XMetaL, whose numbers are similar to Oxygen.

What conclusions, if any, can we draw from this information?



Tech comm problems? Contact us.
Effective October 27, 2011, our physical address is changing to 2327 Englert Drive, Suite 206, Durham, NC 27713
Scriptorium Publishing | Post Office Box 12761 Research Triangle Park, NC 27709 | (919) 481 2701 | info@scriptorium.com