Skip to main content
Opinion

Technical writing and social networks

There is an interesting thread on techwr-l about using social networking sites to deliver product information. In the thread, Geoff Hart notes there is a generation gap in those who turn to unofficial online resources vs. product documentation:

The young’uns go to the net and social networks more than we older folk, who still rely on developer-provided documentation. We ignore this change at our peril. Cheryl Lockett Zubak had a lovely anecdote at WritersUA a few years ago about how she and her son both set out to solve an iPod problem; they both found the solution in roughly equal amounts of time, but she found it in Apple’s documentation, while her son found it on YouTube.

My experience as a user straddles both relying on official docs and information available elsewhere. When my iPod locked up a few years ago, I found decent information on Apple’s web site, but the best resource for my particular problem turned out to be on YouTube. A user had made a video showing step-by-step what to do.

The dilemma of official docs vs. Web 2.0 information partially boils down to question of audience. As part of the process for planning and developing content, technical communicators should evaluate and remember the audience, and that audience consideration now needs to extend to how a company distributes the content. I don’t think there are cut-and-dried answers here; for example, it’s unwise to make the assumption that all folk over a certain age are unaware of or don’t use social networks and other Web 2.0 resources. Ignoring unofficial information channels is certainly not the solution, however.

Read More
News

Think global

All your docs are belong to us.
We are joining with a couple of other technical communication companies to form the TechComm Alliance:

Three companies—Cherryleaf Ltd., HyperWrite, and Scriptorium Publishing—are forming TechComm Alliance to help us handle technical communication projects around the world. We are located in the United Kingdom, Australia, and the United States, respectively, and each company has customers in both its home location and in other countries. TechComm Alliance will make it easier to work with global companies that need services worldwide.

How will this work? We expect to:

  • Work together on large projects that require support in multiple locations. For instance, Scriptorium might be implementing structured authoring for a U.S. company that also has operations in Europe and Australia. During rollout, instead of sending a Scriptorium consultant around the world, we partner with Cherryleaf for the training in Europe and with HyperWrite for the training in Australia. The result? Our customer saves on travel expenses, and our consultants spend less time in airplanes.
  • Refer projects to each other. Each company has (and will continue to have) clients around the world. When we feel that a local presence would benefit the customer, we can refer the project to our alliance partners.
  • Produce webinars and other events together. I’d like for Scriptorium customers to benefit from the expertise of our partners, and we are working on joint webinars.

Read More
Webcast

Documentation as conversation webinar

We have added Documentation as Conversation, presented by Anne Gentle, to our upcoming webinars. Anne is scheduled to present on June 9 at 11 a.m. Eastern time:

Even if your documentation system does not converse with your users, your documentation can help customers talk to each other and make the connections that help them do their jobs well or learn something new as if they were in a classroom with a community for classmates. This talk describes how you can think about documentation and user assistance in a conversational way, with the help of social media technology. I’ll discuss the topics in my new book, Conversation and Community: The Social Web for Documentation. I’ll describe the use of in-person Book Sprints that combine wikis and community events to gather together writers to accomplish documentation goals

Anne is an expert, perhaps the expert, on using wikis and other social media to extend traditional documentation efforts. She’s also an excellent speaker, so I hope you’ll join us for this session.

Register for Documentation as Conversation ($20)

See all upcoming webinars

PS We are working on additional topics and looking for more speakers. Do you have topics you would like us to cover? Please let us know. We are working on a couple of sessions on document conversion.

Reblog this post [with Zemanta]

Read More
Opinion

Death to Recipes!

I love food. I enjoy cooking and I especially enjoy eating. One of my favorite web sites is epicurious.com, and the kitchen shelf devoted to cookbooks sags alarmingly. Many Saturday mornings, you will find me here.

But I am not happy about how recipes have insinuated themselves into my work life. For some reason, the recipe is the default example of structured content. Look at what happens when you search Google for xml recipe example. Recipes are everywhere, not unlike high fructose corn syrup. Unfortunately, I am not immune to the XML recipe infiltration myself.

I understand the appeal. Recipes are:

  • highly structured content
  • well understood

But I think the example is getting a little tired and wilted. Let’s try working with something new. Try out a new kind of lettuce, er, example. This week, I’m trying to write a very basic introduction to structured authoring, and I’m paralyzed by my inability to think of any non-recipe examples.

I’m considering using a glossary as an example. After all, it’s a highly structure piece of content whose organization is well understood. Maybe I’ll use food items as my glossary entries. Baby steps…

PS It’s totally unrelated, but this article about two chefs eating their way through Durham (“nine restaurants in one night, at least five hours of eating and drinking”) is quite fun.

Read More
Conferences

DocTrain’s demise and a challenge to presenters

Unfortunate news in my inbox this morning:

I regret to announce that DocTrain DITA Indianapolis is cancelled. DocTrain/PUBSNET Inc is shutting down.

As a business owner, messages like this strike fear in my heart. If it could happen to them…gulp. (This might be a good time to mention that we are ALWAYS looking for projects, so send them on over, please.) My condolences to the principals at DocTrain.

Meanwhile, I’m also thinking about what we can do in place of the event. I had a couple of presentations scheduled for DocTrain DITA, and Simon Bate was planning a day-long workshop on DITA Open Toolkit configuration.

So, here’s the plan. We are going to offer a couple of webinars based on the sessions we were planning to do at DocTrain DITA:

Each webinar is $20. We may record the webinars and make the recordings available later, but I’m not making any promises. Registration is limited to 50 people.

Here’s the challenge part: If you were scheduled to present at DocTrain DITA (or weren’t but have something useful to say), please set up a webcast of your presentation. It would be ultra-cool if we could replicate the event online (I know that the first week in June was cleared on your schedule!), but let’s get as much of this content as possible available. If you do not have a way to offer a webinar, let me know, and I’ll work with you to host it through Scriptorium.

And here’s my challenge to those of you who like to attend conferences: Please consider supporting these online events. If $20 is truly more than you can afford, contact me.

Read More
Conferences

Back from Atlanta, STC wrapup

The STC Summit was fun as always. My slides are below, but first some other observations.

David Pogue was an excellent keynote speaker. And he sang!

Attendance was lower than last year, but traffic at our booth (and others from what I heard) was up. I think this was a combination of a better location for exhibitors, shorter exhibit hours (Wednesday was cut), and perhaps more senior and more serious attendees.

The biggest change from previous years had to be the use of social media in general, but especially Twitter:

  • The #stc09 hashtag got a serious workout, the tweetup drew 50 or 60 people, and there was constant chatter about the conference online.
  • There was a complementary online event, #stcnotthere.
  • As we were leaving the conference in sketchy weather, #stuckinATL_stc09, created by @lisajoydyer, helped us chronicle the various airport delays and find each other at the airport. It made the delays almost bearable.
  • Rachel Hougton’s flickr feed captures the feel of the entire event, ranging from the Georgia Aquarium and the World of Coca-Cola to the honors banquet and lots of casual photos. (great job, Rachel, btw)
  • You can find a collaborative liveblog on scribblelive.

Interestingly, it seems as though fewer people blogged the event; instead, they were tweeting. However, Keith Soltys did put up day-by-day summaries on Core Dump, and Gryphon Mountain Journals has some reactions. I was unable to find any other live-blogging; if I missed you, please leave a comment.

Tom Johnson interviewed numerous people (including me) at the event. His interview with Ginny Redish is already available.

The tweeting and other social media augmented the actual event. There were people tweeting for lots of reasons: to solve problems (chairs needed), organize groups for dinner, provide sound bites from presentations, and more. The organizing committee put up a twitter feed on a monitor next to their booth and got lots of attention.

I get the impression that the tweets gave non-attendees a flavor of the event. If you were following #stc09 but not attending, did this make you more likely to consider attending in 2010?

Ironically, one of my presentations was actually about technical communication and Web 2.0 issues. I have a white paper on this topic, which is far more useful than the slides. (OK, if you insist, the slides are also available.)

My second presentation was presumptuously entitled “The State of Structure.” This presentation discusses the results of our industry survey on structured authoring, which was conducted in January and February 2009.

If you want more information, the survey report is $200 and available in our store.

Read More
Content strategy Localization XML

Building efficient multilingual workflows

STC Intercom, April 2009

A common argument for XML-based workflows is that they automate production and localization tasks. With XML, localization can be reduced to a fraction of its original cost, but how exactly does that happen?

Sarah explores automization in localization and two technology standards used in multilingual workflows: The Extensible Stylesheet Language (XSL) and XML Localization Interchange File Format (XLIFF).

Download the PDF PDF file (125 K)

Read More
News

Structured authoring in technical communication

I am pleased to announce the publication of our newest white paper, The State of Structured Authoring in Technical Communication. In early 2009, we conducted a survey on structured authoring; this document presents the results of the survey along with our analysis.

Those who participated in the survey are entitled to a free copy of the report. If you requested a copy via email, you will receive a message within the next 2 business days with download instructions. If you requested a printed copy, those will go in the mail tomorrow.

The report is also available for purchase and immediate download. The cost is $200 for the 38-page report (plus 18 pages that reproduce the survey questions, so the file is 56 pages long).

I’m also delivering a presentation at next week’s STC Summit in Atlanta, which discusses the results of the survey. If you’re attending the conference, I hope you’ll join me on Monday, May 5, from 1:30 to 2:30 p.m. in Regency V for “The State of Structure.”

Read More
News

DITA adoption increasing overall structured authoring adoption

I’m knee-deep in survey data analysis. With over 600 responses, our recent structured authoring survey was hugely successful–thank you. Many respondents added candid details about their experiences with structured authoring implementation–their fears, mistakes, and biggest surprises.

The survey report will be available later this month (free to participants, $200 for others), but I wanted to give you a couple of preliminary highlights:

  • About 30 percent of respondents said that they are currently using structured authoring.
  • There’s a lot of hype around DITA, but our data indicates that it’s backed up by reality. Consider this chart, which shows the top three types of structure (custom, DocBook, or DITA) implemented, being implemented, or planned.

DITA accounts for the vast majority of structure implementations--past, present, and futureDITA dominates the chart. But it looks as though DITA is additive. That is, it’s not cannibalizing the numbers for DocBook or custom structures. Those numbers are relatively flat. Instead, it looks as though DITA is increasing the total number of implementations.

If you are attending the STC Summit this year, I’m doing a presentation on the survey results on Monday, May 4, at 1:30 p.m., called “The State of Structure.”

Read More