Skip to main content

Author: Sarah O'Keefe


Technology matters

[Update, March 5: corrected the graphic. It now shows that increased expertise does not produce increased value on the limited curve and does produce increased value on the unlimited curve.]

It’s the third rail of technical writing debates: writing ability or technical expertise? And this week, I ran across two articles that argue that good writing is the key to successful technical writing.

I agree that good writing is important. It’s just that I think that domain expertise and tools expertise are also important. To succeed as a technical communicator, you need all three of these qualifications. (A healthy sense of skepticism about any information that you are given is also helpful. Trust, but verify.)

Here, we have Sandhya, the outgoing President of STC’s India chapter:

If I’ve managed to make a minor dent in a paradigm shift away from the importance of tools and years of experience to the importance of basic technical communication and leadership skills, I’d be thrilled. (Sandhya, 7 Habits of Highly Effective Technical Communicators, INDUS)

These skills are not mutually exclusive, and technical writers need all of them. An excellent writer with more experience is better than an excellent writer with less experience. An average writer with great tools knowledge is better than an average writer with average tools knowledge.

That said, I think there’s a point of diminishing returns.

Diminishing returns for extra tools knowledge

Diminishing returns for extra tools knowledge

The value curve for writing ability follows the “unlimited” line. But the value curve for tools expertise is different. Once a writer exceeds the baseline required tools knowledge, there’s not much additional value in additional tools expertise. That’s the limited curve. (The curve for domain expertise depends on the topic, I think. If you write about consumer software, you’re probably on the limited curve. If you write about highly specialized topics (biochemistry, semiconductors, nuclear medicine), domain expertise is probably on the unlimited curve.

Here is another perspective from Ramana Murthy:

A good product documentation is one that helps users achieve their goals easily, irrespective of the tool it has been authored with – be it RoboHelp, Author-it or the unglamorous Microsoft Word. Product documentation does not arrive with a label like “Developed with the best documentation tools”; nor are there instances of customers preferring product documentation authored with a particular tool. (Ramana Murthy, Technical Communication: Content is the key, tcworld)

True , but it’s also irrelevant. The corporation who is paying for content to be created may care a great deal if option A allows you to create content better, faster, or (especially) cheaper than option B.

The tools and technologies you choose for your content-creation efforts matter because they affect the quality and the development cost of your final deliverables. And therefore, in addition to writing ability, technical communicators must master the required tools, technologies, and templates at the appropriate level.

Read More

Sleepless in Seattle—our agenda at WritersUA

Simon Bate and I will be attending WritersUA this year.

I will be mainly camped in Scriptorium’s exhibit booth. Hours for that are Monday 8:00 am – 6:00 pm and Tuesday 8:00 am – 5:30 pm. Please stop by when you get a chance. Simon will be joining me, but is also presenting on XSL Techniques for XML-to-XML Transformations on Monday at 3:25. Here’s a bit of the description:

In a recent project, we used XSL to correct markup and fix conversion errors in 55,000 XML files containing 2000-year-old Greek texts. The clean-up work included correcting errors in the Greek numbering system, converting text-based markup to XML, replacing or repairing missing markup, and ensuring the accuracy of our work in such a large document set. This session uses this work to illustrate how XML-to-XML transforms differ from XML-to-output transforms. Along the way we describe some XSL techniques we created for processing XML data in which there is a close relationship between the content and the markup.

This year, we’re bringing swag in the form of free copies of The Compass, a printed compilation of Scriptorium white papers. For WritersUA, we have two new white papers, and the book is now almost 200 pages long. (Our white papers are also available, for free, in HTML and PDF format.)

If that’s not a sufficiently sweet enticement, you can also expect local chocolates. The leading contender is currently Fran’s, but I’m open to suggestions, especially from Seattle locals. (We generally pick up chocolate once we arrive rather than attempting to ship it. Ask me some about the Great Truffle Shipping Debacle.)

Simon and I are both scheduling private meetings during the event. If you are a current or prospective client of ours, or if you just want to talk, let us know and we’ll set something up.

Read More
Conferences Opinion

Conferences versus social media

The information you can get from a conference presentation is usually available online—in blogs, webcasts, forums, and/or white papers. So why should you invest the time and the money to attend an event in person? In the end, there’s something very powerful about eating and drinking with a group of people. (And no, alcohol is not required, although it doesn’t hurt. Until the next day, when it hurts a lot.)

The value of conferences, which is not (yet) replicated online is in the “hallway track”—the discussions that happen between the formal sessions:

“[B]eing able to establish a one-to-one personal connection with other professionals in your field is critical to being a success.” (Dave Taylor in The Critical Business Value of Attending Conferences)

“I’ve found that time and again, I’ll hear speakers or audience members or participate in conversations and lie awake that night jam-packed with new ideas (some that don’t even correspond remotely to the concepts discussed that day). Conferences are a brainstorming paradise and a terrific opportunity for new ideas to come bubbling to the surface.” (Rand Fishkin, The Secret Value of Attending Conferences)

Scriptorium has quite a few social media “features”:

  • This blog, started in 2005
  • Webcasts, 2006 (recordings available for recent events)
  • Forums, this week (currently in the “awkward silence” phase. Help us out by posting, please!)
  • Twitter

But there’s something missing. I’ve attended and presented quite a few webcasts, and I can tell you that it’s actually far more difficult to deliver a compelling webcast than a compelling conference presentation. As the presenter, you lose the ability to gauge your audience’s body language. As an attendee, you have the temptation of your email and other distractions. The audio coming through your computer or phone is somehow not real—it’s easy to forget that there’s an actual person on the other end giving the presentation online. (There’s also the problem that many webcasts are sales pitches rather than useful presentations, but let’s leave that for another time.)

In my experience, it’s much easier to sustain online friendships with people that I have met in real life. Even a brief meeting at a conference means that I will remember a person as “that red-haired woman with the funky scarf” rather than as an email ID or Twitter handle. So, I think it’s important to go to conferences, meet lots of people, and then sustain those new professional relationships via social media.

In other words, conferences and social media complement each other. Over time, I think we’ll see them merge until a new interaction model. For example, we are already seeing Twitter as a real-time feedback engine at conference events. (Here’s an excellent discussion of how presenters should handle this.) Joe Welinske’s WritersUA is experimenting with a community site tied to the conference.

What are your thoughts? How important are conferences to your career?

Read More

Talk amongst yourselves…introducing

Our web site now has forums for discussions of technical communication issues. We want to give you, our readers, a venue where you can set your own agenda instead of just responding to our blog posts.

Given Scriptorium’s particular interests, I expect to see a lot of emphasis on publishing automation and XML. But frankly, we don’t know exactly what might happen. Communities often develop in unexpected ways. It will be up to you—and us—to figure out what direction these forums go.

(We have an internal pool on how long before Godwin’s law is applied.)

The forums are available in our main site navigation. There are also RSS feeds so you can subscribe to a topic or category of interest. Or, if you prefer, you can get email notifications for new forum posts.

And how do we feel about this launch? We’re…perfectly calm.

Please join the conversation.

Read More

The elephant in the room—publishers and e-books

Two years ago, Nate Anderson wrote this on ars technica:

The book business, though far older than the recorded music business, is still lucky enough to have time on its side: no e-book reader currently offers a better reading experience than paper.

That’s what makes Apple’s iPad announcement so important. Books will now face stiff competition from e-books as the e-book experience improves.

Elephant in the room // flickr: mobilestreetlife

Elephant in the room // flickr: mobilestreetlife

Meanwhile, the publishing industry (with the notable exception of O’Reilly Media) is desperately trying to avoid the inevitable. (For a slighty happier take, see BusinessWeek.)

Publishers are supposed to filter, edit, produce, distribute, and market content. pre-Internet, all of these things were difficult and required significant financial resources. Today, many are easy and all are cheap.

There’s only one other thing.


But the revenue split between publishers and authors does not—yet—reflect the division of labor. The business relationships are still built on the idea that authors can’t exist without publishers. In fact, it’s the reverse that’s true.

Only the big publishers can get your book into every bookstore in the country. However, I’ve got news for you: Unless your name is on an elite shortlist with the likes of Dan Brown, John Grisham, Nora Roberts, and J.K. Rowling, it probably doesn’t matter.

If you know your audience, you can reach them at least as well as a big publisher can. And you need to reach a lot fewer people to succeed as an independent. The general rule of thumb is a 10-to-1 ratio. You’ll make the same amount selling 10,000 books through a traditional publisher as 1,000 books on your own.

It’s not so difficult to hire freelancers (especially in this economy) to edit and produce your book, if that’s not your cup of tea. Distribution is doable—Amazon is easy, bookstores a little more challenging. This is where e-books will accelerate the change—the challenges of shelf space and returns simply disappear.

And even if you have a publisher, they will expect you to do most of the marketing.

So, what will successful publishers look like in 2020?

  • They will provide editorial and production support for writers who do not want to deal with technical issues.
  • They will support authors in marketing by helping them with blogging platforms and other social media efforts.
  • They will get a much smaller cut of revenues than they currently do.

Actually, that looks a lot like Lulu.

    Read More
    Content strategy XML

    XML: The death of creativity in technical writing?

    Originally published in STC Intercom, February 2010

    I spend a lot of time giving presentations on XML, structured authoring, and related technologies. The most common negative reaction, varied only in the level of hostility, is “Why are you stifling my creativity?”

    Does XML really mean the Death of Creativity for technical communicators? And does creativity even belong in technical content?

    Read More
    Opinion Webinar

    Behold, the power of free

    Lately, our webcasts are getting great participation. The December event had 100 people in attendance (the registered number was even higher), and the numbers for the next few months are strong, as well. Previous webcasts had attendance of A Lot Less than 100. What changed? The webcasts are now free. (Missing an event? Check our archives.)

    We’re going in a similar direction with white papers. We charge for some content, but we also offer a ton of free information.

    The idea is that free (and high-quality) information raises our profile and therefore later brings in new projects. I’m not so sure, though, that we have any evidence that supports this theory yet.

    So, I thought I’d ask my readers. Do you evaluate potential vendors based on offerings such as webcasts and white papers? Are there other, more important factors?

    PS Upcoming events, including several DITA webcasts, are listed on our events page.

    Read More

    XML for Lone Writers?

    My December article for STC Intercom, XML & Lone Writers: Can They Go Together? is now available. From the conclusion:

    The relatively low percentage of lone writers who have implemented XML is a logical result of the typical lone writer working environment. Although it is possible for lone writers to implement XML, a very cautious evaluation of the idea is definitely in order. Given the current status of the authoring and publishing tools, any lone writer who implements XML will need to master fairly demanding tools and technologies.

    The stars of this article are the members of the Lone Writer SIG mailing list, who generously responded to a request for information.

    XML & Lone Writers: Can They Go Together? (PDF, 200K)

    Read More

    2010 predictions for technical communication

    It’s time for my (apparently biennial) predictions post. For those of you keeping score at home, you can see the last round of predictions here. Executive summary: no clear leader for DITA editing, reuse analyzers, Web 2.0 integration, global business, Flash. In retrospect, I didn’t exactly stick my neck out on any of those. Let’s see if I can do better this year.

    Desktop authoring begins to fade

    Everyone else is talking about the cloud, but what about tech comm? Many content creation efforts will shift into the cloud and away from desktop applications and their monstrous footprints (I’m looking at you, Adobe). When your content lives in the cloud, you can edit from anywhere and be much less dependent on a specific computer loaded with specific applications.

    I expect to see much more content creation migrate into web applications, such as wiki software and blogging software. I do not, at this point, see much potential for the various “online word processors,” such as Buzzword or Zoho Writer, for tech comm. Creating documents longer than four or five pages in these environments is painful.

    In the ideal universe, I’d like to see more support for DITA and/or XML in these tools, but I’m not holding my breath for this in 2010.

    The ends justify the means

    From what we are seeing, the rate of XML adoption is steady or even accelerating. But the rationale for XML is shifting. In the past, the benefits of structured authoring—consistency, template enforcement, and content reuse—have been the primary drivers. But in several newer projects, XML is a means to an end rather than a goal—our customers want to extract information from databases, or transfer information between two otherwise incompatible applications. The project justifications reach beyond the issues of content quality and instead focus on integrating content from multiple information sources.


    Is the hype about social media overblown? Actually, I don’t think so. I did a webcast (YouTube link) on this topic in December 2009. The short version: Technical communicators must now compete with information being generated by the user community. This requires greater transparency and better content.

    My prediction is that a strategy for integrating social media and official tech comm will be critical in 2010 and beyond.


    The days of the hermit tech writer are numbered. Close collaboration with product experts, the user community, and others will become the norm. This requires tools that are accessible to non-specialists and that offer easy ways to manage input from collaborators.

    Language shifts

    There are a couple of interesting changes in language:

    • Content strategy rather than documentation plan
    • Decision engine (such as Hunch, Wolfram Alpha, and Aardvark) rather than search engine

    What are your predictions for 2010?

    Other interesting prediction posts:

    Read More