Palimpsest

Palimpsest has moved

2009-09-23T13:47:00.002-04:00

If you are reading this, then we have succeeded in migrating our web site over to WordPress.

Of course, the process of managing our own content always takes a back seat to working with our customers’ content, so the process took longer than you might expect.

But I hope you like the new site and blog. Please update your RSS reader, poke around, and leave us feedback.

On the Shoulders of Open Source

2009-08-20T11:29:00.003-04:00

Every time I mention that we are exploring a new open source application to help support our customers, our Business Development VP, Matt Arnold, asks the very reasonable question, “How do these guys make a living?” I usually mumble something about “support services, extensions, customizations.” This is probably just to make me feel like they are making a living. I do this with the knowledge that a goodly part of my own living is dependent on many people whose hard work I don't feel like I do enough to acknowledge or support.

Recently my wife and I entertained a friend and his new lady-friend. She mentioned that her 27-year-old son wrote software for an open source rendering engine for game developers. Without thinking nearly hard enough about the social graces, I popped out with Matt's standard question: “How does he make a living?” To which she replied, fortunately with a laugh, “He doesn't.”

I suddenly had visions of a pale young man living in a basement, his resume a mile long with hard, complex work, and no one to help him pay his bills but a sympathetic mother. I was imagining, of course, but you get the point.

The difficulties I have in supporting open source applications are complicated. For one thing, I and my coworkers are busy people who focus on supporting our own customers and their demanding schedules. To be blunt, there is seldom time.

Sometimes we make improvements to open source tools, but these are in response to customer needs. Our customers own the fruits of our labors. We might conceivably build clauses into our contractual agreements that allow us to migrate improvements back into the open source community – but having spent a brief period as an expediter of commercial contracts in an engineering corporation, I can assure you that it isn't going to happen. Legal departments around the globe are twitching and flinching in their beds, wide-eyed and sweating obscure Latin legal terms at the thought. (This is not to say that it doesn't happen occasionally – but I would say it is not common.)

We do provide a certain amount of help to the open source community through implicit testing, bug discovery, and clarification in the form of forum questions. But I can recall more than one problem we have had with an open source tool that could have been addressed with a small donation earmarked for a certain fix. This would have benefited the entire community as well as our customers, and it probably would have been done more efficiently. As it happened, because we had a specific commercial contract, we developed the solutions ourselves. And it is difficult for us to justify spending our own money on a software issue that is really our customer's.

General donations are probably needed and deserved – but then one starts to wonder about the reasons open source applications are open source. Isn't it good for things to be free, because that means people are doing things for all the right reasons, so we get good software made by people who want to make something good? And isn't part of the theory that in an open source community, multitudes of people contribute small, affordable chunks of time so funding isn't needed? (And this happens how often? Most of the open source applications I know seem to depend on one or a few dedicated people who are making a living by – other means. I don't ask.)

We can also ask the question, where exactly do donations go? Would I be able to see itemized account books for an open source application if I asked for it?

One situation we have found is that when we do work for the academic community, they are eager and happy for our work on open source tools to be fed back to the source. This makes sense for them, of course, because they are in the business of fostering improvements in the intellectual community. And if I have learned anything about the academic world, it is that they appreciate free tools.

I don't know if there are any firm conclusions to be drawn out of all this, and I'm sure the topic could be explored in much more detail. It does seem to me that commercial businesses need to explore some kind of model for supporting open source tools, similar to the academic community. As a consulting company between large customers and small development resources, it is sometimes an awkward balancing act. It is a complicated problem, but it is also clear that many people benefit from the hard work of a community who are chronically underappreciated and often, as I have discovered, personally underfunded.

If you have thoughts or examples about business support for the open source community, I would like to hear them.

The long and winding roads from DITA XML to PDF output

2009-08-20T10:00:00.000-04:00

DITA XML is of little use to readers unless it's converted to some kind of output. The DITA Open Toolkit (DITA OT) provides transforms and scripts that convert DITA to PDF output and a long list of other formats.

Producing PDF output from DITA content can be challenging. DITA XML is converted to an XSL-FO file, a combination of content and formatting instructions. You must know XSL-FO to customize the PDF, even just to add simple content such as headers and footers, logos, and so on.

To forgo the programming, you can choose a page layout or help authoring tool, but these tools also have pitfalls. Page layout programs have varying degrees of DITA support. Help authoring tools let you style the PDF through CSS, but you can't fine-tune page layout as you can in page layout programs.

These are just a few examples we discuss in our white paper "Creating PDF files from DITA content." Read the white paper online (in HTML or PDF).

Closeout sale on second edition of Technical Writing 101: now $12.95

2009-08-19T09:00:00.006-04:00

We still have a few copies left of the second edition of Technical Writing 101. I want these last copies out of the office (how's that for truth in advertising?), so I have marked them down to $12.95. You can get free shipping within the U.S. when you purchase through our store.

We're also offering the book for $12.95 through our Amazon.com store, but there is no free shipping there. (We're also selling slightly damaged copies at Amazon for $10.95.)

If you prefer to get the latest edition, you can download it in PDF format for $20.

New Webinar Series: Things to consider when moving to DITA

2009-08-12T10:29:00.002-04:00

Scriptorium and JustSystems are announcing a three-webinar series on preparing to use DITA.

The first two webinars in the series describe the age-old problem of converting legacy content into DITA. Because a great deal of unstructured content is in either Adobe FrameMaker and Microsoft Word, we're dedicating one webinar to converting Unstructured FrameMaker to DITA and the other to converting Microsoft Word to DITA.

The third webinar describes various re-use strategies you can apply to your DITA content.

The dates and times for the conversion webinars are:

Converting Unstructured FrameMaker to DITA - August 25, 2:00pm Eastern time.

Converting Microsoft Word to DITA - September 1, 2:00pm Eastern time.

The date and time for the third webinar (DITA reuse strategies) will be announced toward the end of August.

All of the webinars in the series are free, but you do have to register before attending. To sign up, follow this link to the JustSystems web site:

http://na.justsystems.com/webinars.php

Learn DITA and XML at your desk

2009-08-10T09:02:00.003-04:00

For August and September, our webinar schedule is as follows:

DITA 101, August 18 at 11 a.m. Eastern time

Participants will learn about basic Darwin Information Typing Architecture (DITA) concepts, the business case for implementing DITA, and some typical uses of DITA. This webinar is ideal for those who are considering a move to structured authoring based on the DITA standard. Register

Demystifying DITA to PDF Publishing, September 10 at 11 a.m. Eastern time

When a company implements a DITA-based workflow, the most difficult technical obstacle is often setting up a PDF/print publishing workflow. This session discusses the advantages and disadvantages of using the DITA Open Toolkit, FrameMaker, InDesign, and other options to create PDF output from DITA content. Basic familiarity with DITA, Extensible Markup Language (XML), and related technologies is helpful but not required. Register

What Do Movable Type and XML Have in Common?, September 22 at 11 a.m. Eastern time

The invention of movable type changed the economics of information by making the process of copying a book by hand obsolete. More than 500 years later, XML seems to be doing the same to desktop publishing. But where movable type changed the economics of a mechanical process—creating printed  copies—XML changes the economics of content authoring, formatting, and customization. This webinar takes a look at how publishing technologies revolutionize the way people consume information and how those technologies affect authors. Register

Each webinar is $20.

During the sessions, you can interact with the presenter and other students through the chat interface or the audio connection. There is a question-and-answer session at the end of each webinar. The Q&A is not included in session recordings, which are available for download later. Participants in the sessions receive a free recording.

To register for these webcasts, or to purchase recordings of past webinars, go to our online store.

Let the conversation begin

2009-08-05T10:19:00.000-04:00

Conversation and Community: The Social Web for Documentation (XML Press, ISBN: 9780982219119) by Anne Gentle provides technical communicators with a roadmap for integrating social media -- blogs, wikis, and much more -- into their content development efforts. This is critical because, as Anne notes in the preface, "professional writers now have the tools to collaborate with their audience easily for the first time in history."

Anne provides overviews of all the major social media concepts -- from aggregation to syndication, wikis, discussion, presence, and much more. But it is Chapter 3, "Defining a Writer's Role with the Social Web," that will make this book a classic. Here, Anne lays out a detailed strategy for determining whether and how to introduce social media in an organization. Consider this:

It's important to find a balance between allowing an individual's authentic voice to speak on behalf of an organization and the requirements of institutional messaging and brand preservation. [...] It's also possible that you are ahead of the curve and need to help others see ways to apply social technologies for the company.

She goes on to explain just how to accomplish these things.

Wikis and blogs each get a chapter of their own, in which Anne discusses how to start and maintain these types of environments.

After reading so much of Anne's work on her blog, it's a bit odd to see her writing on paper in an actual book. The feeling that I've wandered into the wrong medium is augmented by extensive footnotes, most of which point to web site resources, and the many examples of web-based content (such as videos or interactive mashups). However, it's likely that the book's target audience is more comfortable with paper.

Conversation and Community: The Social Web for Documentation provides an excellent introduction to wikis, blogs, forums, and numerous other social media technologies for the professional content creator. There is valuable (and perhaps career-preserving) information about how to develop a strategy for user-generated content that is compatible with your organization's corporate culture.

If you think that community participation in your documentation is coming soon, read this book immediately. If you think that it's not coming, you're wrong, and you especially need to read this book.

Resources:

Sample chapter (PDF)

XML Press book page

Amazon order link: Conversation and Community: The Social Web for Documentation

[Disclosure: I reviewed an early draft of this book. I have met Anne in person a few times and we have ongoing email and blog correspondence.]

Manifest(o) destiny

2009-07-29T23:26:00.001-04:00

Tom Johnson issues a polite manifesto about moving STC's publications online. (I am distracted by the use of the word manifesto and more so by its Wordnik page. I'd like to blame this problem on the Internet, but I'm pretty sure that the Internet just lets me manifest (!) my attention problem more easily. OK, I'm banning "manifesto" from the rest of this post.) Here's Tom:

When I hear these discussions, it blows me away because I can hardly believe what I’m hearing. I admit, the look and feel of paper can provide a comfortable reading experience if you’re immersed in a 200 page novel lying on your bed on a rainy day. But the Intercom and other professional magazines or journals are not novels. With professional publications like these, the online format better matches the reading behavior of the audience. In fact, online formats provide more than a dozen advantages that print formats lack, including everything from interactivity to portability, feeds, metrics, multimedia, and more.

I am fundamentally in agreement with Tom's manif....er, declaration of principles. For balance, I would like to address the advantages of printed content over online content. They include the following:

Higher resolution

The printed page generally has a resolution of 600 dpi (printed at the office) or 1200 dpi (printed on a printing press). On-screen, you have a resolution of around 100 dpi. Therefore, printed content has a resolution that's around 36x higher than screen content. (100 dots per inch is 100 pixels times 100 pixels, or 10,000 pixels per inch. 600 dpi is 360,000 pixels per inch.)

There are other technical issues (such as light being absorbed/reflected on paper versus being emitted from a screen) why text on paper is easier to read than text on screen.

Batteries and electrical power

Paper doesn't require batteries or electricity to operate. This matters most for toilets and airplanes. And airplane toilets.

Universal access format

Once you have a paper copy, you can access your data. The same thing is not necessarily true online. For instance, you can have browser compatibility issues with HTML, problems with PDF versions, digital rights management obstacles, problems with logons for private content, and so on.

Better layout

Print (and PDF) give you sophisticated options for layout that go far beyond what you can do online with HTML.

Familiarity

As a society, we have hundreds of years of experience with books and magazines. This is not true for online content.

Engaging your senses of smell and touch

I think this issue is often overlooked when evaluating print versus online. The physical experience of holding a book, the smell and feel of high-quality paper, the sensation of pages sliding past your fingers as you turn the page -- all of these are lost in the digital experience.

Authority

Printed content conveys authority in a way that web-based content does not. I believe that this is related to some of the factors I've outlined above. We know how to evaluate printed publications for quality -- we look for attractive design, glossy paper, high-impact color, and so on. There's a reason why the cliché is that you shouldn't judge a book by its cover. We do. (See also: "Understanding Judgment of Information Quality and Cognitive Authority in the WWW," Soo Young Rieh and Nicholas J. Belkin, PDF link)

But even though I can make a decent argument for the merits of printed publications, Tom is absolutely right, at least as it pertains to STC, when he says that:

Any organization or company would be crazy not to convert their paper-based magazine, journal, or newsletter into an interactive online format.

He's laid out (cough) the arguments for online content in some detail, so I am going to focus on something a little different. I'd like to take a look at the business case for moving publications from print to online. I do not have any useful information from STC on the actual costs, so I'm just going to make some estimates. (I would be happy to get the official cost information. Anyone?)

We have around 11,000 members, so let's assume a print run of about that. Further, let's assume that printing runs about $2 per copy (?) and postage about $1 (I have no idea). That gives us an estimate of $33,000 in direct printing and postage costs per issue. Multiply that by 10 issues per year, and you get somewhere around $330,000 in direct printing and postage costs per year. I am leaving out international postage and other complicating factors. There's also the fact that STC is collecting additional funding for sending printed publications.

In addition, each printed issue incurs design and layout costs. Best guess? 100 hours per issue at oh, $50 per hour. So, that's somewhere around $50,000 per year in layout costs.

Some things I am not taking into account:

Initial magazine design. My 100-hour estimate is for flowing content into an existing design, placing graphics, generating the table of contents, and doing print production.
Editing.
Working with recalcitrant authors.
Planning the magazine content/setting the editorial content.
The income side of the equation -- fees specifically for international postage, for example

What would the equivalent costs look like for an XML or HTML-based workflow?

We eliminate printing and postage, so we save $330,000 per year. We probably save on the layout costs as well because publishing into HTML is so much less work. Total cost savings? Conservatively, it's $330,000, if we assume no cost savings from reduction in layout work. (Note: If we continue to publish a PDF version of the magazine, we must keep the PDF layout costs as a line item and add a smaller amount for HTML-based publishing so maybe $300,000.)

I have been told that STC will lose advertising income if the magazine goes online only. I would agree that advertisers will pay less for online advertising as opposed to print advertising, but surely the advertising income would not drop all the way to zero. Let's assume, however, that it does. The best estimate I have for advertising income is $143,159 (from Paul Bernstein's detailed cost breakdown on the STC Ideas forum, accessible here to registered members of the forum).

So, even if advertising drops to zero, we have a net positive of $150,000 from moving online. Implementing an XML or HTML-based magazine for the first time will cost a lot less than that. Therefore, the return on investment appears quite compelling.

You should be aware that I have no confidence in any of the numbers I have compiled here. I do not know the following with any certainty:

Intercom print run
Cost per printed copy
Cost of postage
Income from advertising

However, based on my experience in the industry, I think that the general ballpark figures are probably accurate. I would be delighted to update this post if someone can give me the real numbers.

So, Tom has laid out the argument for moving magazine content online based on quality. I have given you the argument based on cost, along with the reasons why you might prefer print.

What do you think?

In defense of English majors: we can understand business issues, too

2009-07-27T10:34:00.002-04:00

In his latest blog entry, Neil Perlin explains how important it is for technical writers to have an understanding of business issues. With such knowledge, they can contribute to cost justifications for decisions that affect them directly. I couldn't agree more with that. It is absolutely in writers' best interests (and a matter of self-preservation) to understand processes and costs.

I strongly disagree, however, with the following assertion:

Writers from fine arts or English backgrounds can rarely discuss cost-justification in finance terms, so they have little input on buying decisions.

I am an English major, and I freely admit I am more of a "words" person than a "numbers" person. That being said, I am no slouch in the finance department. (Calculus is another matter, though.) I know many people with degrees in English and the liberal arts who are quite adept at understanding The Big Picture and developing business cases. Lumping all of us into a "can rarely discuss cost-justification" group is unfair.

Now I need to remind myself not to group software developers into a "can rarely write a coherent procedure" category. (It's easy to make generalizations when you're not the target of them.)

Lost in translation (and in my brain)

2009-07-23T09:28:00.001-04:00

Last night, a bit of spam managed to worm its way through the filters on a personal email account, and I have to admit I glanced at the content while scanning previews of messages. That's when I spotted a paragraph that really jumped out at me:

They have good management systems, product quality inspection system. And international speedboat (EMS) is the door - door accurate! Soon!

My thought process was, What's up with the international speedboats? And why are emergency medical services (EMS) using these speedboats? I knew that the person who wrote the content was likely not a native English speaker, but I could not figure out what the writer was trying to communicate.

This morning, I finally realized what the message was trying to say: the company uses EMS worldwide delivery services for prompt and accurate delivery to my door. My brain must not have been firing on all cylinders last night when I thought EMS meant "emergency medical services."

I don't think I've ever spent as much time thinking about a company's marketing message, but my thoughts weren't about using the company's services--I was merely trying to comprehend the message itself. That's not what the company intended, I'm sure.

Marketing for a global audience--particularly one that associates EMS with "emergency medical services"--is not an easy thing!

Error message melodrama

2009-07-20T14:38:00.004-04:00

The Shanghai Tech Writer blog has posted a screen capture of a rather ominous error message in FrameMaker:

The licensing subsystem has failed catastrophically. You must reinstall or call customer support.

I have never been the unfortunate recipient of that particular message in the many years I've worked with FrameMaker. If I did encounter that message, I would fully expect it to be accompanied by the shrieking strings from the Psycho shower scene. The use of "catastrophically" is a bit over the top. The fact I need to reinstall or contact customer support sets the tone enough, thank you very much--no soundtrack or scary adverb required.

The editor in me wants "catastrophically" removed from that message. If that bit of text came across my desk for review, I would have pushed back hard on the use of that word. It's bad enough the user has to get a solution to the error, and referring to the problem as "catastrophic" is certainly not doing the user any favors.

Printed version of Technical Writing 101 now sold at infibeam.com

2009-07-17T12:40:00.004-04:00

The printed version of Technical Writing 101 (third edition) is currently available at infibeam.com, which provides free shipping to cities in India. At the time of this posting, Infibeam is offering the book for 1407 rupees (24 percent off the list price).

Those who want instant access to Technical Writing 101 can download it in PDF format from our online store for $20 (USD).

Publishing Fundamentals print/PDF bundle: $24.99 for 24 hours

2009-07-14T08:17:00.003-04:00

Our big sale on Publishing Fundamentals: Unstructured FrameMaker 8 starts tomorrow morning.

From 8 a.m. tomorrow until 8 a.m. Thursday (Eastern time), you can purchase the print and PDF bundle of Publishing Fundamentals: Unstructured FrameMaker 8 for just $24.99. That's half off the list price of $49.99 (and cheaper than the cost of just the PDF download, which is $29.99).

You don't need a coupon code to get the special price: just order within the 24-hour window.

On Wednesday, July 15: big one-day sale

2009-07-10T14:07:00.004-04:00

I always laugh when department stores advertise a one-day sale and then have a "preview day" on the day before. Last time I checked, that's a two-day sale.

Well, we're going to have a big one-day sale on Publishing Fundamentals: Unstructured FrameMaker 8 next Wednesday, and we really mean a one-day sale. From 8 a.m. on July 15 until 8 a.m. July 16 (Eastern time), you can purchase the print and PDF bundle of Publishing Fundamentals: Unstructured FrameMaker 8 for just $24.99. That's $25 off the list price of $49.99--and cheaper than the cost of just the PDF download, which is $29.99.

You don't need a coupon code to get this special price on the print and PDF bundle, and you can order multiple copies, too. Just be sure to order sometime between 8 a.m. Wednesday and 8 a.m. Thursday.

Please spread the word about this sale!

Authoring tools do matter

2009-07-09T11:03:00.001-04:00

"I can write in anything."
"The tool doesn't matter."
"I can learn any new tool."

Most of the time, I agree. But then, there are the exceptions.

One of our customers is using FrameMaker to produce content that is delivered in HTML. (They use structured FrameMaker, generate XML, and then transform via XSLT into HTML.) Their rationale for using FrameMaker was:

The project was on an extreme deadline.
The writers already knew FrameMaker.
FrameMaker is already installed on the writers' systems.

All valid points.

But.

We have had a continuous stream of requests from the writers to make adjustments to the FrameMaker formatting. Things like "the bullets seem a little too far from the text; can you move them over?"

FrameMaker is being used as an authoring tool only. FrameMaker formatting is discarded on export; HTML formatting is controlled mainly by CSS. However, even after repeated explanations, we continue to receive requests to modify the FrameMaker formatting.

In this specific case, the authoring tool does matter. Writers are focusing on the wrong set of issues (leading, kerning, print formatting), none of which is actually relevant for the output.

Why are they focused on this stuff? Because they can. It seems to me that moving authors to a WYSIOO (what you see is one option) tool, such as oXygen or XMetaL, instead of a WYSIWYG tool (FrameMaker) would eliminate the obsession with irrelevant formatting.

Mandatory 80s reference:

Some thoughts on "free"

2009-07-07T02:21:00.000-04:00

Chris Anderson (author of The Long Tail and editor-in-chief of Wired Magazine) has just published Free: The Future of a Radical Price. The book is available (not free) in all the usual outlets, but you can also read it on scribd. For free.

Reviews, so far, are mixed. Malcolm Gladwell, writing in the New Yorker, didn't like it. The New York Times, not so much a fan. And there was an ugly little kerfluffle about attribution (or lack thereof) of content sourced from Wikipedia. Emma Duncan, writing for the Guardian, liked it.

This book is important because Anderson is attempting to define a taxonomy of different types of "free." Business and organizations face the difficult challenge of figuring out what should and should not be free. To give you a tiny, itty-bitty example, Scriptorium offers a series of white papers, technical references, and books. What's the difference between a white paper and a technical reference? The white papers are free, the tech references are not. Costs range from $10 to $200. But how do we decide whether a document should be free or not? We are still trying to figure out the right answer. As Anderson points out, the incremental cost of producing additional e-books (after the first one) is zero. Should all digital content be free? We have chosen, for the most part, to charge for books and for the more technical documents. White papers, which typically provide an overview of a technology or methodology, are generally free. We feel that this is a fair representation of our actual development costs.

Meanwhile, our friendly neighborhood technical communication organization is trying to figure out some similar issues. Currently, the STC web site has public content (free) and members-only content (not free).

The major argument I'm hearing from STC leadership for locking down content is basically that otherwise, people will be able to use the content without paying for it. In other words, the value of the STC membership is that it gives you access to members-only content. This logic would make some amount of sense if STC held a monopoly on content related to technical communication. It does not.

So, what happens when you lock down content and hide it from non-members? You lose the opportunity to participate in the community. You lose the opportunity to have non-members read your content, decide you are useful, and join the Society. You lose the opportunity for inbound links.

Similar logic applies to forums, wikis, and online communities. Members and non-members should be able to participate. Perhaps members get special badges in their profiles to indicate membership, but communities derive value from participation, and open access means more participation.

If stc.org can be transformed into a vital hub for the technical communication community, the organization itself will do fine. In a moment of apparent insanity, I have offered to help with this effort. If you'd like to join me, contact me in the comments below, via Twitter (@sarahokeefe), on the STC Ideas forum (stcideas.ning.com), or via whatever avenue makes the most sense to you. (Email and phone contact information are in the main part of our web site.)

Summer webinar theme: Avoiding extinction

2009-07-06T13:26:00.000-04:00

Ellis Pratt of Cherryleaf is delivering Beyond Documentation this Thursday, July 9th, at 11 a.m. Eastern (US) time. Ellis gave a similar presentation in Vienna, which was the basis for Tom Johnson's post, How to Avoid Extinction as a Technical Communicator, and led to a lively discussion in the comments. Join us to see if you agree with Ellis's point of view.

In the category of "what's old is new again," we have Writing to STOP from Tony Self of HyperWrite in Australia.

STOP - Sequential Thematic Organisation of Publications - was developed at Hughes Corporation in the 1960s. The purpose of STOP was to improve the speed of document production, and to allow multiple authors to work simultaneously on the same document. [...]
The STOP approach still resonates in the age of online documentation, as we still have the same needs to reduce document creation times and to work collaboratively. In this session, we will look at how the STOP approach worked, and how it might be re-applied even more effectively in the 21st century.

That presentation is July 15 at 5 p.m. Eastern time. (Note the time change. Our usual 11 a.m. time slot is 1 a.m. in Melbourne, Australia. That seemed impolite to our presenter.)

Finally, Jack Molisani of Prospring and Lavacon is delivering How to Build a Business Case on August 4 at 11 a.m. Eastern time.

If you've ever submitted a purchase request that was not approved, chances are it lacked one or more of the vital components management looks for when allocating resources.

In this segment, Jack Molisani will present a fun and practical session identifying the components of a successful business case, how to identify what is important to management, how to maximize your chances of approval, and more.

Jack usually rewards questions with chocolate, and I'm going to be impressed if he manages that in a webinar.

Don't miss your chance to hear from these guys. You can register through our store; recordings of previous webcasts are now available as well.

PS Our presenters are based in England, California, and Australia. Registrants could be anywhere. The sessions are yours for $20. I love the Internet.

Congratulations to contest winners...

2009-07-01T13:27:00.003-04:00

...Bjørn Smalbro and Dave Truman, who will receive printed copies of Technical Writing 101.

Thanks to everyone who entered the drawing. Even if you didn't win, you should have received an email with a coupon code for $5 off the PDF download of the book. (If you indicated that you teach technical writing, you should have received a code for a free review copy.)

Keith Soltys posted a review of Technical Writing 101 on his Core Dump blog yesterday. I'm pleased to report the review is positive.

A special alert to my fellow bargain hunters out there: Amazon.com is selling Technical Writing 101 at a steep discount. At the time I posted this blog entry, Amazon is offering the book for $23.73 (34 percent off the $35.95 cover price). The price does fluctuate, so who knows how long that discount will be in effect.

This is the future of technical communication

2009-06-29T10:39:00.001-04:00

First, read this article in the New York Times about the struggle to keep a reporter's kidnapping quiet:

For seven months, The New York Times managed to keep out of the news the fact that one of its reporters, David Rohde, had been kidnapped by the Taliban. But that was pretty straightforward compared with keeping it off Wikipedia.

Now, think about these issues as applied to technical communication. Let's assume that your organization has online community -- forums and a wiki, maybe. Technical communicators are responsible for monitoring and managing the community. Under what circumstances do you delete information? How do you respond when:

Information is inaccurate
Information is unflattering
Both

What if the information is accurate but incomplete?
What if someone describes a way of using your product that could cause injury, even though it's technically possible? Do you delete the information? Do you add a comment warning of possible injury? What if the reader sees the original post but not the comment?

In the absence of safety concerns, I think that accuracy must win. Thus, as the information curator, you have a responsibility to correct inaccurate information. If the inaccuracy is truly dangerous, you may need to edit the post directly. Make sure that you disclosure what you've done with brackets. For example:

I like riding my scooter down mountains, especially without guardrails. Wheee! [This is a really bad idea because You Might Die. -moderator]

or

I like [really bad idea redacted by moderator]. Wheee!

Deleting unflattering (but accurate) information will probably backfire on the organization. Instead of censoring negative content, try addressing the concern being identified. Think of an impolite forum post as customer feedback. Does the poster have a valid point? Can you fix the problem that's been identified?

I hate your scooters. They don't come in enough colors. And they suck.

What colors would you like to see? We do have two dozen available, see this list.
- Joe in TechComm

The life-or-death issues around Mr. Rohde's kidnapping are relatively straightforward. We are likely to have much more difficult judgment calls in typical technical communication. Imagine, for example, that information were being suppressed because it criticized security arrangements and not because of safety concerns for the reporter. In that case, I think we can agree that Wikipedia's response would have (and should have) been different. What would an equivalent scenario look like in your organization?

Enter soon: Technical Writing 101 contest ends tomorrow

2009-06-29T08:05:00.005-04:00

We're giving away two printed copies of Technical Writing 101 (third edition) on Wednesday. Please enter the drawing before it closes tomorrow.

We're giving away the books to celebrate the book's wider release to online bookstores such as Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, and BN.com; you can also place a special order for Technical Writing 101 at your local bookstore. If you want instant access to the book, you can download the PDF version for $20 from our online store.

We achieved this wider distribution by working with another print on demand (POD) company, Lightning Source. We're quite happy with the quality of the books from our other POD partner, Lulu.com. However, at this time, Lulu doesn't offer distribution for publishers who use their own International Standard Book Numbers (ISBNs). We've released books under our own ISBNs since we published the first edition of Technical Writing 101 in 2000, and I frankly was not comfortable assigning an ISBN owned by a POD firm to content we developed. Using a publisher's ISBN would cause problems if we wanted to switch to another publisher later. We'd have to assign a new ISBN, and then the book would be in the marketplace with two different ISBNs. I wanted to prevent that marketing (and distribution) headache from ever happening.

I'm not going to write a long post about the virtues of Lulu.com and other POD publishers vs. Lightning Source because many other people have done that (in this blog post, for example). What I will say, though, is that Lightning Source is geared more toward experienced publishers, and Lulu provides more guidance that newer authors and publishers will certainly appreciate. If you want to get your feet wet in the POD pool, Lulu is a great place to start, but if you're a publisher who has published several titles with your own ISBNs, Lightning Source may be better suited for your needs.

Win a printed copy of Technical Writing 101 (third edition)

2009-06-24T10:01:00.007-04:00

As of this week, the printed version of Technical Writing 101 (ISBN 9780970473363) is available at online bookstores, and you can also special order a copy from your local bookstore. To celebrate the book's wider distribution, we're giving away two printed copies.

Enter the contest by June 30 (next Tuesday). We'll pick two winners at random on July 1.

The printed book is now listed at many online stores, including Amazon.com, Amazon.co.uk, Amazon.de, Amazon.fr, and BN.com. (FYI to all you bargain hunters out there: some of these stores are selling the book at a discount and with free shipping, too.)

For those of you who want instant (and cheaper) access to the book, we're still offering the PDF download (ISBN 9780970473370) for $20. The download (which has been particularly popular with buyers outside the US) is available only through our online store.

Later, I'll write more about how we achieved the wider distribution of the printed version through our new print-on-demand partner, Lightning Source, and how Lightning Source compares to Lulu.com.

Automated trademarking in structured documents – DITA in particular

2009-06-22T13:21:00.005-04:00

Unabashed plug warning: The following entry gives a conceptual overview of a solution Scriptorium has implemented for managing trademarks in structured tagging. And we're proud of it.

You know the problem. According to your style standards, only the first instance of a given trademarked term should display the trademark symbol. Structured documentation allows you to re-use document parts (such as DITA topics) in just about any order you like. In Manual A, the first file containing the trademarked text is, say, Topic A; in Manual B the first file containing the trademarked text is Topic E, which is also used in Manual A. Where do you put your trademark markup, and how do you maintain it when running Manual A and Manual B at approximately the same time?

Maintaining the trademarks by hand adds a level of effort that becomes non-negligible when you start considering a large number of manuals. And the process becomes error prone – those darned human beings. Different writers might tag things different ways, trademarks might escape notice, or markup might be inserted in inappropriate places by accident.

Isn't this one of those problems that automated documentation was supposed to solve, not create? I once had a professor who said that computers were supposed to handle the work that computers could solve so people could work on the problems that only people can solve.

More than one of Scriptorium's customers has presented us with this problem, so we know it is not uncommon. We have found a way to deal with the problem in DITA, and we believe that the principle is sufficiently generic to use in non-DITA structures as well.

To begin with, forget conditional processing. It won't help you with the problem of marking only the first instance of a term. In the example of Manual A, above, setting the condition “Manual A” would still display the trademark in Topic A and Topic E. This is not what your editor wants – and he or she will let you know it in spades if he or she is any kind of editor at all.

Scriptorium's solution for DITA, in simple outline, is as follows:

Using XSL, go through the ditamaps and remove all trademarking from the document files.
Following a predefined list of trademarked and registered trademarked terms, go through the ditamaps and identify the files that contain each term. Create a temporary file that lists the relevant files in order of book occurrence. (This step prevents having to crawl through the ditamaps more than once.)
Using Perl, iterate through the files listed for each term in the temporary file. Check the occurrence of each instance of the term, in text order, and evaluate whether it is a valid occurrence that requires trademarking. If so, wrap the appropriate trademark markup around it and go to the next trademark. If not, keep going through the text and the list of files until you find a valid occurrence of this trademark.

We possibly could have used XSL instead of Perl for the third step, but Perl's text manipulation capability is much more robust than XSL's, so we chose Perl.

In the implementation, the trademarking utility is coordinated by an Ant process. A user runs this utility just before the book is rendered for output. Being in Ant, the trademarking process could probably be integrated into the DITA Open Toolkit build system fairly easily to create a seamless, one-step production process.

There are a number of interesting problems that arise during implementation. For example, in step 3 the process has to evaluate whether the instance of a term is valid for trademarking. Some kinds of non-valid instances of a term in the text might be:

The term is in an indexterm tag.
The term is in an href attribute.
The term is in a title.
The term is in a codeblock tag.

You might also encounter a condition where a trademarked term could be both mixed case and all uppercase. Per your style guide, only the first instance of either should be marked, but not the first instance of both. That sort of requirement makes life just a little more interesting for a coder.

In general, the issue of trademarking first instances is not a simple problem to solve, and variations in style requirements will undoubtedly add complexity and challenges to the problem. But that's what automated documentation is supposed to be good at, right? So we humans can get back to doing the more difficult problems that only people can solve.

I'm not sure – is that really such a good deal?

Whither STC?

2009-06-19T16:11:00.002-04:00

As you may have heard, STC is in a financial crisis. According to the board of directors meeting minutes from May 5, 2009 (PDF, page 2), STC must retain membership "for the next year or STC will be out of business in two years." There's a lively discussion on Twitter under the #stcorg hashtag.

For example, Bill Swallow (@techcommdood) wrote: "From STC I want innovation, education, and communication. Right now I get advertising, magazines, and frustration. #stcorg"

STC itself has requested feedback via private email, on Twitter with the #stcorg tag, and on a "private online forum." I appreciate the idea, but I prefer to share my thoughts here, where anyone can read and comment on them.

According to the June 18 email message from Cindy Currie (STC president), the "unprecedented financial shortfall" is being caused by "the recession's negative impact on our traditional sources of revenue." Although it's certainly true that the recession has caused a decline in membership along with a decline in conference attendance (the biggest two sources of income for STC), the recession is not the root cause of the problem.

The root cause is that STC is not perceived as sufficiently important by its membership. After all, a member could pay $200 for a membership by dropping cable television for a couple of months. Getting rid of cable for a year would come close to paying for conference attendance. It is true, of course, that a few members are in serious financial trouble due to layoffs or reduced income. In most cases, however, I think the member (or the sponsoring employer) has simply decided that STC (or the conference) does not offer enough value to justify the cost.

I have been an STC member for many years, and am an associate fellow. I participate in the annual conference both as a speaker and as an exhibitor. My company is a member of the Corporate Value Program. I have served on a couple of society-level committees and initiatives. This doesn't make me a typical member, but I think it does give me a fairly broad perspective on the organization as a whole.

I believe that STC needs to make some significant changes in the following areas.

Velocity
Industry developments are fast and furious, and STC has not kept pace. For the STC conference, generally held in May, proposals are due the preceding summer. I turned in an article for Intercom on June 16, which will appear in the September issue. Chris Hester (@chris_oh) said it best on twitter: "Why pay for a pub when it uses content that was on blogs months earlier?"

STC needs to increase what the military calls operational tempo. Intercom, as many others have said, probably needs to evolve into an online publication to cut down the publication time. This has some significant advantages:

Faster publishing
Cheaper publishing by eliminating print production, paper, and distribution costs
Ability to publish more often

There is concern that putting Intercom online (and, by the way, I do not mean in PDF format) would put a dent in advertising revenue. It will. However, my company does not currently advertise in Intercom because we think the rates are too high and the value is not there. I would greatly prefer advertising in an online Intercom. I would also expect those rates to be significantly lower than the equivalent print ad. Providing Intercom online would open up advertising to many smaller companies. Would it be more profitable? I don't know, but it would be a better, more relevant, publication, so that's a start.

Similarly, the proposal process for the annual conference needs to be compressed significantly. With nine months of lead time, it's impossible to provide relevant content. And please don't tell me "it can't be done." Joe Welinske of WritersUA usually evaluates proposals in September/October for a March conference. Germany's tekom, which is significantly larger than the STC conference, generally requires proposals in May for a November event. Six months is still a long time, but it's one-third shorter than STC's process.

Community
STC's main value is in providing a sense of community for technical writers/communicators. In the past, the organization delivered community through printed magazines mailed to the membership, through local chapter meetings, and through regional and national conferences. As email lists became popular, STC has provided discussion lists for various SIGs, local chapters, and other groups (for example, there is a chapter presidents' list. Or so I hear).

Today, however, communities of interest are meeting through various social media, and STC has not kept pace. STC should be providing a platform that encourages discussion and collaboration. The obvious template for this is what Scott Abel has done with the Content Wrangler network. STC serves writers; give the writers a place to write blogs, collaborate on a wiki, and the like.

Incidentally, STC Body of Knowledge effort is an excellent example of open collaboration. However, it's quite difficult to find it from the main STC web site. These and other initiatives should all be under the stc.org umbrella. It's not particularly difficult to set up subdomains so that, for example bok.stc.org points to the Body of Knowledge and forum.stc.org points to the forums. And so on.

Openness
Finally, STC needs to embrace a culture of openness. That means:

Provide open access to Intercom and other publications online. Increase the readership, make the publications more relevant, and therefore increase their appeal to advertisers.
Provide open access to forums and other collaboration areas. Do not limit them to members only. The STC Single Sourcing SIG recently launched a Ning network (here), but access is restricted not just to STC members but actually to SIG members only. This balkanization reduces the value of the community. Instead, open up participation and build a valuable, must-have resource.
Improve member communications and especially focus on giving people a way of letting their voices be heard. The virtual town halls now in progress are a good idea, but the process of getting access is too difficult. I finally resorted to begging for help on twitter and got the information I needed in less than five minutes. Unless there is a compelling reason to lock up information, it should be publicly available.

Change is hard. Transformational change is painful.
I have worked with many of the people in the STC office and in STC leadership, and it's important to recognize that they are hard-working, smart people. I like them. (One of them is particularly entertaining in a hotel bar at 1 a.m. You Know Who You Are.)

They see the icebergs ahead and are trying hard to navigate through them. The problem is that turning a cruise ship takes time and effort. And, if you'll pardon the tortured analogy, the larger problem is navigating through the ice field is impossible with a huge cruise ship. The correct answer is to step outside today's constraints and rethink the problem. Perhaps we should morph into a submarine and go under the icebergs. At this point, we are still discussing whether to make a 5-degree or a 10-degree turn.

The financial problem that STC faces is a symptom, not the disease. Let's treat the symptom and get through this crisis, but please do not forget about the underlying disease. STC needs more velocity, more community, and more openness.

Update (6/23/2009): Since I published this post, several other bloggers have added their perspectives. Here they are, in no particular order. If I missed your post, please add it in the comments so that readers of this article can find you.

Lifelines to the STC, Tom Johnson, I'd Rather Be Writing
In Which I Comment on the STC Issue, Keith Anderson, mkanderson.com
Does the STC Deserve to Survive?, David Farbey, The Blockhead Blog
It's STC Not STW, Alan Porter, 4J's Group
The STC Crisis: The take of a "young" writer, Paul Pehrson, Technically Speaking
Bye bye STC, Gordon McLean, one man writes
STC Floundering?, Keith Soltys, Core Dump

Flare 5 DITA feature review, part 2

2009-06-17T14:00:00.000-04:00

[Alan Pringle wrote most of this review.]

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

DITA support level
Flare supports DITA v1.1.

Our verdict

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

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

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

2009-06-12T10:05:00.001-04:00

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

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

The initial coverage reminds me a bit of this:

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

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

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

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

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

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

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

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

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

Beyond that, we have the following:

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

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

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

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

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

Notice that:

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

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

<title>Executive summary</title>

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.