Skip to main content

Author: Sarah O'Keefe

DITA Webinar

Webcast: Demystifying DITA to PDF publishing

When you implement a DITA-based workflow, you face myriad new challenges, such as getting accustomed to topic-based writing, exploring reuse strategies, and specialization. The most difficult technical obstacle is usually setting up a PDF/print publishing workflow. The DITA Open Toolkit provides very basic PDF output, but for organizations who require attractive, professional-looking PDF content, extensive and expensive customization is required. FrameMaker is easier to configure than the Open Toolkit and produces lovely PDF files, but can you work around the limitations of the DITA support? InDesign offers the highest quality typography but has significant limitations in working with structured content. This session discusses the advantages and disadvantages of each approach to extracting PDF from DITA content.

This session is intended for individuals who are considering a DITA implementation and expect to need PDF output. Basic familiarity with DITA, XML, and related technologies is helpful but not required.
NOTE: During the recording, the presenters will mention polls. You will not see these polls while viewing the recording, but the presenters will describe the results.

Read More

Angst and authority

Clay Shirky has a fascinating post on the concept of algorithmic authority; the idea that large systems, such as Google PageRank or Wikipedia have authority (that is, credibility) because of the way that the system works. In other words, a page that is returned first in a Google search is assumed by the searcher to be more credible because it is ranked first.

That made me think about authority in technical content.

As an in-house technical writer, your words have authority and your content carries the corporate logo. But although this should theoretically increase your credibility, it seems that the reverse is true. Consider, for instance, the following hypothetical book titles:

  • XYZ User’s Guide—This document, produced by the makers of XYZ, is shipped in the product box (or downloaded as a PDF with the software)
  • XYZ Classroom in a Book—This document is available in bookstores and is produced by XYZ Press
  • XYZ: The Complete Reference*—This document is available in bookstores and is produced by a third-party publisher

Which of these books would you turn to for help? What are your expectations of each document?

I believe that credibility and thus authority increases with distance from the product’s maker. In other words, the third-party book has more authority than either of the other two. Credibility is compromised by close association with the organization that makes the product.

When we apply this concept to information on the web, the implications are troubling for professional content creators who work inside corporations. If corporate authorship decreases authority, we get this result:

online help < user forums on corporate site < user forums on third-party site

Will people looking for user assistance gravitate toward independent third-party sites? What does that mean for in-house authors? How can you increase your credibility as a corporate technical communicator?

* Feel free to substitute your favorite book series title: XYZ for Dummies, XYZ: The Missing Manual, The Complete Idiot’s Guide to XYZ, XYZ Annoyances, …. I should probably also mention that I have written both a Dummies book and a Complete Reference.

Read More

Coping with webcast participation

Many thanks to all of the people who attended yesterday’s webcast on coping with user-generated content.

We recorded the webcast, and it is now available:

In a nod to the topic itself—and in an effort to make the event more interesting, I solicited quite a bit of audience participation. As a result, I owe the webcast participants a significant number of links and other resources.

Question: What blogs do you read?

Answer: Lots.

Better answer: Here is a link to my Google Reader subscriptions in the Publishing category. Many thanks to the attendee who recommended sharing them this way. (If you’d like full credit by name, send me email or put a note in the comments; I don’t want to do that without permission.) I’ve also listed the blogs at the bottom of this post.

In addition to the publishing blogs, I specifically mentioned Punk Rock HR, Dooce, and Mark Logic CEO blog. (Don’t read the first two if you are offended by a word that starts with F.)

Question: Are there any guides to legal issues in social media, such as libel?

Answer: I found a few interesting resources, but not a definitive guide.

Libel and Social Media (blog post)

IBM Social Computing Guidelines (these have been in the news as a template for a well-crafted policy)

Read More

To bid or not to bid—a vendor’s guide to RFPs

Request for Proposal (RFP) documents usually arrive in the dead of night, addressed to sales@scriptorium or sometimes info@scriptorium.

Dear Vendor,

LargeCompany is looking for a partner who can work magic and walk on water. Please refer to the attached RFP.


Somebody in Purchasing

Our instinct is to crack open the RFP and start writing a proposal. But over time, we’ve learned to take a step back and evaluate the RFP first to ensure that it’s worth our time.

In this post, I’ve outlined some of the issues that we consider before responding to an RFP.


Are we qualified to do the work that the RFP is asking for? More importantly, are we qualified in the customer’s eyes? Many RFPs delineate evaluation criteria, which may not be relevant (in our opinion) to the task at hand. For example, we once saw a proposal for an Interleaf to FrameMaker conversion project that demanded expert knowledge of Interleaf. I would think that expert knowledge of FrameMaker would be more important, but the customer wanted Interleaf knowledge. FrameMaker was mentioned in passing. We decided in that case that our expert knowledge of the Interleaf-to-FrameMaker conversion process(es) should compensate for our minimal Interleaf expertise.

But if the RFP demands expertise that we simply do not have, and if that expertise, however irrelevant, will be weighted heavily in the evaluation, investing in a proposal is risky. The fact that we know we can do the project well is irrelevant if that customer will discard our proposal for lacking a required element.

Some days you’re the windshield, some days you’re the bug

It’s critically important to figure out whether an RFP is really looking for a vendor or not. Especially in large organizations and for larger projects, multiple bids are often required. The customer may already know exactly who they want to work with, but their purchasing department requires a minimum number of bids (usually three). Thus, the customer writes an RFP to get “column fodder”—the sacrificial second and third proposals to go along with the vendor that they really want.

We have experience on both sides of this issue. Sometimes, we’re the preferred vendor; sometimes, we’re the one getting the unwinnable RFP. Identifying cases where we have no chance of getting the business is critical to avoid wasting our time. Unfortunately, it’s also a bit of a black art. But here are some factors to consider:

  • Did the RFP parachute in from nowhere, or have we had previous contact with the organization?
  • Are there unusual requirements in the RFP? (For example, we decided against responding to an RFP that stated that close proximity to the customer would be a significant weighting factor. Not-so-coincidentally, one of our competitors just happened to have an office nearby.)
  • Is the project a marginal fit for our services? (In an effort to find additional vendors, the purchasing department might do a quick Google search and then broadcast the RFP. For instance, we get quite a few RFPs requesting outsourced technical writing services. Not the best fit for us.)
  • Is the customer unwilling to have a conference call to discuss questions we have about the RFP?

Most importantly, if your intuition tells you that there’s a problem, pay attention.


First and most importantly, is the project funded? In one painful case, we wrote a proposal and made the trek to the customer’s office (which was, naturally, on the other end of the country) to present our solution. (This site visit was explicitly required under the terms of the RFP.) Six weeks later, we found out that the evaluation committee had presented their recommendation to upper management and had been denied funding. In other words, the people who issued the RFP did not have approval for the project.

Assuming that funding is in place, there is the question of whether the funding will be sufficient. If the customer thinks their problem can be solved for $20,000 and our proposal totals $100,000, the sticker shock alone will probably be enough to kill our chances. This is why we often ask prospects about their expectations: how long do they think the project will take? How many people do they think should be assigned to the project? In some cases, we ask directly what the budget is.

How are bids evaluated?

RFPs that demand a list of services and hourly rates are a bad sign. Interestingly, government RFPs usually spell out evaluation criteria, using language such as this:

Selection of an offeror for contract award will be based on an evaluation of proposals against four factors. The factors in order of importance are: technical, past performance, cost/price and Small Disadvantaged Business (SDB) participation. Although technical factors are of paramount consideration in the award of the contract, past performance, cost/price and SDB participation are also important to the overall contract award decision. All evaluation factors other than cost or price, when combined, are significantly more important than cost or price. In any case, the Government reserves the right to make an award(s) to that offeror whose proposal provides the best overall value to the Government.

Corporate RFPs seem to avoid any mention of evaluation criteria, other than to state that certain items are required in a proposal or the proposal will be deemed “non-responsive.” The dreaded “non-responsive” label is attached to a proposal that does not meet the requirements of the RFP. For instance, if the RFP indicates that a response must include resumes and resumes are not included, the entire proposal could be discarded as non-responsive.

Evaluating risk

The decision whether or not to bid on an RFP comes down to evaluating the risk. Factors include:

  • Do we have other RFPs that look more appealing?
  • Are the deadlines reasonable (both for the proposal and for the project described therein)?
  • How many others will respond to the proposal?
  • How well does the customer understand the issues?
  • Does the RFP demonstrate an understanding of the problem the customer is trying to solve?
  • Has the customer already decided on their preferred solution and do we agree with the approach they want to use?
  • Are the evaluation criteria clear and relevant?
  • What is the pricing structure?
  • Does the project look interesting to us?
  • Do we want to work with this customer?

Of course, even with all these factors, the decision often hinges on intuition. Perhaps there’s something not quite right about the RFP. Turning away work (or potential work) is always difficult, but I think we’re getting better at sniffing out RFPs where we truly stand no chance of success. Or perhaps, despite several risk factors, we believe that we can work well with the customer and make a useful contribution.

Read More

The revolution will not be authorized

In the past few days, STC has been sending out acceptance notices for presentations at next May’s STC Summit. There’s been a small flurry of announcements, mostly on Twitter. (I live in North Carolina where two flakes are a flurry. 10 flakes are a school-closing, bread-and-milk-buying emergency.)

For instance, we have this on Friday, November 20:

Tweets related to STC acceptances

Tweets related to STC acceptances

Side note: I’ll be presenting on managing in an XML environment.

In the pre-Twitter Era, acceptances were sent by mail, and then conference organizers could post the full program more or less at their convenience. But now, the leaks start almost immediately.

This may not be a bad thing. The happy tweets raise awareness of the event. For an organizer, however, it means that notifications need to be carefully synchronized or perhaps staggered on a formal schedule (SxSW does this quite well; they announce program decisions in batches).

It seems like another case where unofficial community content is eroding the ability of the content owner to control the messaging. Coincidentally (!), that’s the topic of a webcast I’m doing on December 8.

Strategies for coping with user-generated content
Tuesday, December 8, 11 a.m. Eastern time

We are offering this webcast for free; you just need to register.

This is a new presentation that I first delivered at LavaCon in New Orleans this year.

Read More

Fear the peer

(This post is late. In my defense, I had the flu and the glow of the computer monitor was painful. Also, neurons were having trouble firing across the congestion in my head. At least, that’s my medical explanation for it. PS I don’t recommend the flu. Avoid if possible.)

Which of these scenarios do you think is most intimidating?

  1. Giving a presentation to a dozen executives at a prospective client, which will decide whether we get a project or not
  2. Giving a presentation to 50 people, including half a dozen supportive fellow consultants
  3. Giving a presentation to 400 people at a major conference

I’ve faced all three of these, and while each scenario presents its own set of stressors, the most intimidating, by far, is option #2.

In general, I’m fairly confident in my ability to get up in front of a group of people and deliver some useful information in a reasonably interesting fashion. But there is something uniquely terrifying about presenting in front of your peers.

Torches // Flickr: dantaylor

At LavaCon, I faced the nightmare—a murderers’ row of consultants in the back of the room, fondling various tweeting implements.

Here are some of the worst-case scenarios:

  • No new information. I have nothing to say that my colleagues haven’t heard before, and they could have said it better.
  • Disagreement. My peers think that my point of view is incorrect or, worse, my facts are wrong.
  • Boring. I have nothing new to say, my information is wrong, and I’m not interesting.

Of course, my peers were gracious, participated in the session in a constructive way, and said nice things afterwards. I didn’t even see any cheeky tweets. (I’m looking at you, @scottabel.)

All in all, I’d have to say that it’s a lot more fun to sit in the back of someone else’s presentation, though. Neil Perlin handled his peanut gallery deftly, asking questions like, “With the exception of the back row, how many of you enjoy writing XSLT code?”

Rahel Bailie said it best, I think. After completing her excellent presentation, she noted that presenting in front of peers is terribly stressful because, “I really want you to like it.”

Read More
Conferences Webinar

Free the webcast!

In addition to our November event on localization, we are adding another webcast in December. I’ll be presenting Strategies for coping with user-generated content on December 8 at 11 a.m. Eastern time via GoToWebinar. This event is free but registration is required.

Here’s the description:

The rise of Web 2.0 technology provides a platform for user-generated content. Publishing is no longer restricted to a few technical writers—any user can now contribute information. But the information coming from users tends to be highly specific.

The two types of information can coexist and improve the overall user experience. User-generated content also offers an opportunity for technical writers to participate as “curators”—by evaluating and organizing the information provided by end users.

Remember, there’s no charge to attend, but you do need to register.

Date: December 8, 2009
Time: 11 a.m. Eastern
Topic: Strategies for coping with user-generated content

PS Depending on the response to this event, we are going to consider additional free events.

Read More

A mercenary view of STC

STC has announced their new dues structure.

To summarize:

  • Dues are going up.
  • Printed publications are no longer included in basic dues.
  • No chapter or SIG membership are included in the basic dues.
  • There are still tiered dues for “persons located in low and lower middle-income countries as classified by the World Bank,” but those dues have also increased.

Predictably, reaction is largely negative, such as this comment from Julie Ross:

Good luck, STC! Your membership is not worth $215, especially when it includes less than it did before! I will not renew at these increases. Money better spent in other ways.

I have been a freelancer/business owner for the vast majority of my career (so far). Let me say a few things about STC’s value proposition for mercenaries like me.

Flickr: amagill

Money // Flickr: amagill

Cold, hard cash

My participation in STC events, especially the annual conference, has led to enormous amounts of business for my company. Let’s take just one example: During an STC conference a few years ago, I was approached by representatives of a government agency to discuss a major project. (I found out later they had attended my session to see if they wanted to talk to me. I apparently passed that test.) That meeting resulted in a new customer and over $250,000 in revenue for Scriptorium.

We ask customers and prospective customers how they found us. “I saw you at a conference” is a common answer. I don’t have exact figures on how much revenue we derive from conference participation, but I know that it’s significant. Even if we only get one project a year from an event, the investment is worthwhile.

Those of you who are freelancers or consultants probably have similar experiences. Conferences are an excellent marketing tool. If you are a regular employee or the thought of speaking in public makes you ill, this argument is perhaps less compelling, which brings me to…

Wishing well // Flickr: dystopian

Wishing well // Flickr: dystopian


It’s become a cliché that networking is the best way to get a job. But I think a lot of people approach this the wrong way:

  1. Oops, I lost my job.
  2. Time to do some networking.

Wrong. Networking is a lifelong project. If you want help getting your next job, you need to lay the groundwork months or years ahead of time. Got a job opening at your current employer? Send it out to respected colleagues. Have an acquaintance who’s been laid off? Help them out; offer to review or proofread their resume. When you need help (and believe me, at some point we all do), your network will return the favor.

At the last STC chapter meeting I attended, at least 30 percent of the people there were unemployed. I wonder how many of them started attending meetings only because they need a job. A long time ago, I read Dig Your Well Before You’re Thirsty by Harvey Mackay, and I highly recommend it if you want some advice on how to become a successful networker.

Let’s say you change jobs once every five years or so. And let’s assume that networking inside STC can help you get a job just a few weeks faster than you would on your own. If you make $60,000 per year (for easy math purposes), that’s $5000 per month or about $1250 per week. Five years of STC dues is around $1,000. If you can find employment even one week sooner, your STC investment breaks even. If you find a job two weeks faster, you come out ahead.

I’m not even addressing the case where your network helps you find a better job where you make more money or improve your commuting time. What’s that worth to you?

You do not want to be a paper clip. Flickr: bbaunach

Don't be a paper clip // Flickr: bbaunach

Avoiding commoditization

The mission of STC is to “advance the arts and sciences of technical communication.” How does this help you, the member?

If STC succeeds, you are more likely to find jobs that pay well because your work is respected.

You are less likely to be the first person laid off in a downturn.

You are less likely to find job postings that include general office work among technical communication tasks.

You are less likely to be replaced by another, less skilled, less expensive writer.

In short, if technical communication is valued, your work is less likely to be viewed like a commodity.

Commoditization is very, very bad for your income and employment prospects. Paper clips are commodities to be procured at the lowest possible cost. Quality is rarely an issue. You do not want to be a paper clip.

Based on these major factors, the value of STC is clear to me.

Read More
Conferences Webinar

Coming attractions for October and November

October 22nd, join Simon Bate for a session on delivering multiple versions of a help set without making multiple copies of the help:

We needed to generate a help set from DITA sources that applied to multiple products. However, serious space constraints prevent us from using standard DITA conditional processing to create multiple, product-specific versions of the help; there was only room for one copy of the help. Our solution was to create a single help set in which select content would be displayed when the help was opened.
In this webcast, we’ll show you how we used the DITA Open Toolkit to create a help set with dynamic text display. The webcast introduces some minor DITA Open Toolkit modifications and several client-side JavaScript techniques that you can use to implement dynamic text display in HTML files. Minimal programming skills necessary.

Register for dynamic text display webcast

I will be visiting New Orleans for LavaCon. This event, organized by Jack Molisani, is always a highlight of the conference year. I will be offering sessions on XML and on user-generated content. You can see the complete program here. In addition to my sessions, I will be bringing along a limited number of copies of our newest publication, The Compass. Find me at the event to get your free copy while supplies last. (Otherwise, you can order online Real Soon Now for $15.95.)

Register for LavaCon (note, early registration has been extended until October 12)

And last but certainly not least, we have our much-anticipated session on translation workflows. Nick Rosenthal, Managing Director, Salford Translations Ltd., will deliver a webcast on cost-effective document design for a translation workflow on November 19 at 11 a.m . Eastern time:

In this webcast, Nick Rosenthal discusses the challenges companies face when translating their content and offers some best practices to managing your localization budget effectively, including XML-based workflows and ways to integrate localized screen shots into translated user guides or help systems.

Register for the translation workflow webcast

As always, webcasts are $20. LavaCon is just a bit more. Hope to see you at all of these events.

Read More

Strategy < tactics < execution

I read Execution: The Discipline of Getting Things Done several years ago, and much of this post is based on the information in that book. 

Because of a Series of Troublesome Committees, I find myself thinking about three big-picture concepts: strategy, tactics, and execution:

  • Strategy is the overall plan. For example, one strategy for getting new projects at Scriptorium is to establish ourselves as experts in our chosen field.
  • Tactics are specific actions to achieve the plan. Our tactics include writing articles and delivering conference presentations that buttress our claim of expertise.
  • Execution is what happens after you pick a strategy and develop some tactics. That’s when we write the articles and attend the conferences.

Each of these stages is a prerequisite for the other. That is, you start by developing a strategy and can then pick your tactics. Finally, you have to execute on the plan.

You can fail at every point in the process:

  • Choose the wrong strategy, and not much else matters. Great tactics and excellent execution will not rescue you if you have chosen the wrong approach.
  • If you have the right strategy, but the wrong tactics, you may have some limited success, but poor tactics will work against you.
  • Worst of all, though, is bad execution. You pick the right strategy and the right tactics, and then sabotage the whole thing with poor follow-through or lousy performance. For example, writing an article full of bad grammar or delivering a boring, technically inaccurate presentation would be bad execution for us.

At every stage, you face constraints. For instance, if your budget is limited, you might not be able to justify the most expensive tactic, even though it might have been the most effective. But once you work through your constraints and choose your tactics, there’s really no excuse for doing those activities badly.

Some things to keep in mind when working with technical communicators:

  • Forget the spin. Exorcising marketing and PR messages from technical content is a core job skill for many of us. Simple, honest, and straightforward messages are better. If you try to spin your message, expect a scornful response.
  • Language matters. Writers become writers because they care about language. If you want their respect, you need to show that you also care about language. At a minimum, grammar and mechanics need to be accurate. If you can go beyond the basics and demonstrate graceful writing, you will score bonus points.

Read More