Random thoughts about publishing

Site Feed

Labels

Palimpsest has moved. Please visit our blog in its new location for the most recent posts from Scriptorium.

Palimpsest

 

Let the conversation begin

Wednesday, August 05, 2009 — posted by Sarah O'Keefe

Labels: book, reviews, web 2.0

10:19 AM Permalink | |

 

This is the future of technical communication

Monday, June 29, 2009 — posted by Sarah O'Keefe

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?

Labels: web 2.0

10:39 AM Permalink | |

 

More cowbell!

Thursday, June 04, 2009 — posted by Sarah O'Keefe

About a year ago, we added Google Analytics to our web site. I have done some research to see what posts were the most popular in the past year:

1. The clear winner was our FrameMaker 9 review. With 21 comments, I think it was also the most heavily commented post. Interestingly, the post itself is little more than a pointer to the PDF file that contains the actual review.
2. InDesign CS4 = Hannibal post, which discussed InDesign's encroachment on traditional FrameMaker features.
3. A surprise...a post from 2006 in which Mark Baker discussed the merits (or lack thereof) of DITA in To DITA or not to DITA

Our readers appear to like clever headlines, because I don't think the content quality explains the high numbers for posts such as:

• Zohoho, and a bottle of rum
• A technical writing ditty

We noticed this pattern recently, when a carefully crafted, meticulously written post was ignored in favor of a throwaway post dashed off in minutes with a catchy title (Death to Recipes!).

For useful, thoughtful advice on blogging, I refer you to Tom Johnson and Rich Maggiani. I, however, have a new set of blogging recommendations:

1. Write catchy titles
2. Have an opinion, preferably an outrageous one
3. More cowbell

Labels: blogs, cowbell, humor, web 2.0

8:00 AM Permalink | |

 

Technical writing and social networks

Monday, June 01, 2009 — posted by Alan Pringle

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.

Labels: technical writing, web 2.0

10:40 AM Permalink | |

 

Documentation as conversation webinar

Friday, May 22, 2009 — posted by Sarah O'Keefe

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.

Labels: presentations, web 2.0, wiki

8:38 AM Permalink | |

 

The XML Strategist: Web 2.0 as the Tipping Point for XML

Monday, January 12, 2009 — posted by Sarah O'Keefe

My latest column in STC's Intercom, Web 2.0: The Tipping Point for XML, is now available:

User-generated content is going to be hugely disruptive for technical communication. Your content strategy needs to include Web 2.0, and XML provides a platform to support the seamless integration of “professional” content with “user” content.

As always, I'm quite interested in reader feedback.

Labels: web 2.0, xml strategist

2:06 PM Permalink | |

 

Taxonomy of web content delivery

Thursday, September 11, 2008 — posted by Sarah O'Keefe

I really like the new article from Richard Hamilton on the Content Wrangler, in which he describes various categories of web content delivery, ranging from "no-ware" to "shovel-ware" to "active-ware."
Active-ware is "anything that lets you interact with users online." And most interestingly, Hamilton points out that:

Active-ware is orthogonal to the other categories and suggests that successful approaches to Active-ware will draw from a different set of models than the other categories.

You might also describe "active-ware" as Web 2.0 content. In which case, you might find our Friend or Foe? Web 2.0 in technical communication white paper of interest.
(Side note: These white papers are now available as HTML and you can rate each page and leave your comments.)
Hamilton implies that the role of the technical writer will change for Web 2.0 content (active-ware). He writes:

[... S]ome of the things we value most in technical communication, like good writing and complete and accurate solutions, may have less importance, if any, in Active-ware.

I started my career in technical communication as a production editor. Technical writers wrote content, technical editors reviewed the information for grammar, mechanics, and completeness, and the production editors were responsible for verifying that the documents were formatted correctly and printed properly.
These days, production editors and technical editors are endangered species. Some organizations have eliminated production editors with automated formatting (usually an XML-based workflow); other organizations place the responsibility for final document appearance on the technical writers. In neither case do we have people whose primary responsibility is to give content that final gloss.
As a former production editor, I find this unfortunate -- and the formatting errors that are so abundant in today's technical content make me cringe. But from a business perspective, I understand the reasoning -- for most organizations, the value added by checking pagination, fixing awkward line breaks, and verifying formatting is not great enough to justify the expense. (A few organizations, especially those in consumer electronics and similar industries, still emphasize high-quality printed manuals.)
Which brings me back to active-ware, which is often of lower quality than traditional technical communication because it's poorly written, not complete, and not entirely accurate (as Hamilton says in the quote above). Active-ware, however, has one huge advantage: immediacy. On a forum, you can ask a question and expect help within hours or even minutes. If the documentation doesn't address your particular issues, waiting months for the next release of the documentation is probably not a viable solution.

Labels: analysis, web 2.0

10:13 AM Permalink | |

 

A cautious toe in the water

Tuesday, September 09, 2008 — posted by Sarah

[Updated to add link to Gilbane Group, which I accidentally left out. -Sarah]

Over at the Gilbane Group blog, Fred Dalrymple writes about social media, aka Web 2.0, aka user-generated content:

Integration [with technical documentation] means, somehow, placing social media into an iteration loop in the documentation supply chain.

He believes that a prudent first step could be to work with customers:

For example, it's easy to imagine deploying a documentation set via a wiki that issuing and client companies can both update, perhaps with a dedicated editor at the source company to keep brand, message, and metaphors consistent. That leaves the challenge of how that material gets integrated back into the supply chain so that it can feed the next release...
These are early thoughts, and tools such as wikis are low-hanging fruit. How will the less document-centric media be integrated? What new forms of relationship will develop around these practices? How can this be extended to independent outsiders?

It sounds totally reasonable. But the general focus of the post is on controlling branding and message. And I believe that the general implication of Web 2.0 and many-to-many publishing is that corporations are going to lose the ability to control the conversation.

Dalrymple says:

Let's assume that when social media is being practiced by independent outsiders, it will be a matter of chance whether their behavior is consistent with a corporation's goals.

This misses the larger point. If the end users want the corporation to have different goals from what the corporation actually has, the corporation will need to respond! The answer is not to control, direct, and manipulate social media so that it conforms with the preferred brand messaging. The answer is to recognize that the corporation's goals need to change.

For example...let's say that a company releases a new operating system. Let's call it, oh, "Vista." And perhaps the company's goal is to sell this "Vista" to the entire world. But users respond by heaping scorn on the new release, demanding downgrades the previous operation system, and, most drastically, switching to other operating systems.

The problem is not those mean, angry bloggers writing rude things about the product. The problem is with the product.

If the social media world is telling you things that are not compatible with your brand and product positioning, it means that you have a problem with the brand and the product -- not with the users.

Labels: analysis, web 2.0

12:40 PM Permalink | |

 

Wacky wiki

Monday, September 08, 2008 — posted by Sarah

We recently made our FrameMaker 7 workbook content available in a public wiki. We simply don't have the time to make the needed updates to get the content to version 8, so we thought that we'd let you, the general public, have editable access to it.

The results have been enlightening and, at least to me, unexpected:

1. Nobody is making updates. We have a significant number of people who have registered as users on the wiki, but they aren't making changes to the content.
2. Sales of the fully formatted, not-free PDF versions of the workbooks have increased significantly.

According to Chris Anderson, this second effect is actually what we should have expected for a Web 2.0 platform. He describes the "freemium" model "where 90% of the users get the basic product for free and 10% chose to pay for a premium version."

One of my coworkers thinks that people are using the wiki to window-shop. They verify that the content looks useful and then go ahead and pay for the official version. So the wiki provides reassurance about the paid product's quality.

Your thoughts?

Labels: FrameMaker, web 2.0, wiki

2:13 PM Permalink | |

 

Adding color commentary to white papers

Friday, August 22, 2008 — posted by Ethan Duty

When Scriptorium wrote on Web 2.0 back in April, we mentioned creating HTML versions of our white papers. Those papers are now live, ready for your ratings and comments.

You can link to them below or from our white papers page.

Friend or Foe: Web 2.0 in Technical Communication

Structured Authoring and XML

Managing Implementation of Structured Authoring

Is DITA Right for You?

Integrating XML and FrameMaker

Labels: comments, ratings, web 2.0, white papers

1:06 PM Permalink | |

 

Digital rights management in Web 2.0

Tuesday, July 08, 2008 — posted by Ethan Duty

The argument for digital rights management (people will steal your stuff) sounds good from a retail perspective. Who would buy the book when they can get a pirated copy for free? But if retail sales aren't the focus of your company, there is value in the illegal proliferation of your stuff.

This does not mean piracy is good. Pirates take from the producer without investing anything back, leaving that producer with fewer resources to make better stuff, and thus slowing the progress of knowledge, technology, and perhaps civilization as we know it. But piracy is an additional form of marketing. Unprotected content results in additional readers at the expense of lost sales. But "free" content will reach consumers that cannot afford or justify the cost of a book, so your content gains exposure to individuals who otherwise would not have access to the information.

Let's say you're a consultant. You attract your clients by being the authority on certain information. One way to prove your authority (see the connection, authority and author) is to create white papers and books that others find useful.

The more people that read and use your stuff, the bigger an authority you become on the topic. If piracy drastically increases the copies of your books being used, you have that many more people that recognize your authority.

The more individuals that recognize your authority, the more likely they are to come to you for answers not available in the book. Since cloning isn't perfect, the public cannot pirate your personal knowledge and experience, and you get to charge the money for consulting services.

With everything going to the web, attention is rising in value. Your content is just one drop in a vast ocean of stuff and announcing your existence and value to potential clients becomes ever more difficult.

If pirated copies of a book generate more searches on the author and drive traffic to your site or blog, then perhaps there will come a time when you can't afford DRM.

Labels: business, DRM, web 2.0

1:07 PM Permalink | |

 

Web 2.0 and Truth

Thursday, June 26, 2008 — posted by Sarah

My presentation at X-Pubs was about the impact of Web 2.0 or user-generated content on technical communication. (You can view the presentation at the bottom of this post.)

A phrase I heard repeatedly in reference to professional content was "a single version of the truth," which alludes to the idea that you should only have one instance of any given piece of content.

And that got me thinking. There are many areas of tech comm where this idea makes sense.

User-generated content, though, is in direct conflict with a single, unchanging, objective truth. Wikis, by definition, have content that is constantly evolving.

Furthermore, there's truth and then there's, well, truth. Compare and contrast these two snippets:

"The ABC feature is unusable. Use the XYZ as a work-around."

"You can use ABC to do blah blah. Here's how:
(many annoying steps)"

Which one is truth? Both? More importantly, which one is more useful to the reader?

It takes a brave or maybe foolish corporate technical writer to criticize their own product explicitly. (This, in turn, is probably why third-party computer trade books sell so well. Somehow, I don't see a title like Word Annoyances getting the Microsoft seal of approval.)

But even though technical writers try to act as user advocates, there's a built-in conflict of interest -- technical writers are paid by corporations, not by users.

User-generated content meets a need that corporate technical publications do not (or perhaps cannot). It provides unfiltered, opinionated, and user-biased coverage of technical topics.

Why is there a gap between professionally created technical publications and the end users?

1. Updates can take a long time to get into the official documentation because of lengthy review, approval, and publishing processes.

2. Annotation capabilities are rarely provided to users. If they are, they're usually fairly limited.

3. The documentation is not sufficiently candid.

What are the implications for technical writers?

1. Document publishing needs to accelerate.
2. Online documents should allow for comments and discussion.
3. The documentation needs to be explicit about product limitations and workarounds.

In effect, technical writers need to have more of an editorial voice.

Here is my Web 2.0 presentation:



Notes: Use the arrow keys to navigate through the slides. The first slide may take a few seconds to come up; the presentation file is quite large.

Labels: analysis, conferences, web 2.0, xpubs

11:21 AM Permalink | |

 

X-Pubs keynote: Transforming Legislation Publishing

Monday, June 23, 2008 — posted by Sarah

Brief introduction from Noz Urbina and an overview of the conference from Julian Murfitt. Some X-Pubs housekeeping items, including a flight announcement...

"Should a presentation be boring and sleep deprivation set in, oxygen masks will drop from the ceiling. Please put on your own mask before assisting others."

Hehe.

On to the keynote...John Sheridan, Head of e-Services at the Office of Public Sector Information, National Archives. Eeek, slight problem with slides -- and the presenter just launches right in without them. I bet he's terrified right now, but he looks perfectly composed.

We have slides. "Transforming Legislation Publishing"

Publishing legislation seem dry, but in fact it's quite relevant to the people at large -- and ignorance of the law is no excuse. Legislation documents use XML under the covers. Have been publishing legislation online since 1996 and of course print for a long time before that.

Strengths of their service:

• Immediacy: published online simultaneously with print versions. Important because some measures go into effect the day of their enactment.
• Accuracy: value of service hinges on knowing that the rendition of the online content is the same as the official vellum statement signed by the Queen. (Vellum? Really??)

• Trust: Do customers trust that what they see online is an official source? Based on eye-tracking software, they found when asked about trust, customers looked at the official crest and then responded positively.
• Reach: 1.5 million users, mostly in the UK

Much of the content they were republishing online had not been touched in 10 years or so. However, they had as many as 500,000 external links (that is, links from other web sites pointing to their content). Breaking links was out of the question because the number of links help their content's Google rankings.

Key performance indicator: two clicks. 80 percent of information should be available in two clicks:

1. Google search button.
2. Click link on first page of results.
   

Their audience is demanding. Challenges included:

• Legacy workflows
• Multiple document inputs. Coming from Parliament, government lawyers in 21 departments, Scotland, secondary legislation, Welsh measures, legislation from Northern Ireland, church materials, dual languages in Wales (English and Welsh).
• Tools include: FrameMaker for some groups; Word for others
• Legacy content: 55,000 documents that needed to be repurposed from SGML to XML to improve web publishing.

Primary motivation to improve usability and accessibility of content. Existing HTML content didn't look contemporary.

Persistent linking, "web continuity", overall 60 percent of links to official information are broken. Their solution to "persist" the 500,000 existing links was to provide redirection behavior, so that every URL resolves either to live content or to the government's archive on the web.

XML is the key to solving these assorted issues.

Trying to "future-proof" their work, especially by providing a way to allow for changing web standards (HTML/web standard may change, but we can keep underlying XML).

Legislative documents are highly structured but also have variations over time. Very difficult to capture in a structure. "Parliament trumps your XML schema." You can't say, "Sorry, but that won't work in our schema, so you can't pass that legislation." Must find the balance between accommodating what's needed and "allowing everything."

They developed Crown XML:

The Crown XML Schema for Legislation provides a full and comprehensive encoding for all United Kingdom primary and secondary legislation. It has been written using the World Wide Web Consortium XML Schema language and is the Government's official and authoritative data standard for legislation. Once a piece of legislation has been enacted or made, it is stored using this Schema format. Schema compliant legislation is available in XML for onward supply to legal publishers and others.

They provide sample documents, which even so cover only about half the possibilities in the full schema.

Users have options for various views of the legislation.

Their work leads to the concept of the web as a platform. Not just providing for users to consume, but also to reuse, aggregate, and combine.

Mixing data...hey, cookie dough!

The government's response to Web 2.0 trends. Government should enable information so that citizens can use the information. Doing so will lead not only to better public services, but also to other services, both commercial and noncommercial.

Problems include culture, rights, licensing, intellectual property, and technology challenges. Information becomes infrastructure and potentially as important as roads and other physical infrastructure. Legislation is widely cited content, which becomes infrastructure for other things. Legislation needs to be addressable with fragment identifiers, so that people can cite specific sections or paragraph rather than an entire act.

Why couldn't lawyers add editorial value to legislation in a wiki-type format. Not a job for the state, but something that could be enabled or inhibited by how the legislation is published. Providing addressable content and using standards would allow for third parties to use the legislation as a starting point for additional work.

They provide Atom (RSS) feeds for new legislation.

Library of Congress is an example of a re-user of UK legislation. UK legislation of interest for comparison purposes. They have a "PDF thing going on." Really wanted access to PDF versions of the information. Subscribe to the Atom feed, and the PDF will pop up there as a link.

Expect reuse for very granular areas...discussion of specific industries or topics. (If mad cow disease were to reoccur, expect footpaths to be closer, and a map could show in real-time what's open and what's closed.)

Providing sufficient flexibility into structure without descending into tag soup.

First question: Is the raw XML available to the public?
Yikes. The presenter hesitates and is quite uncomfortable. Seemed like a harmless enough question but apparently not. The answer is that it's available by subscription -- that is, lawyers pay to get access to it. They must balance between their economics and subscription income. They would like to publish XML; seems to be the direction that public policy is going. But "don't want to spend taxpayers' money to subsidize Lexis-Nexis."

Second question: Would these policies extend to others, like the Department for Transport?
Again, this sounds harmless to me, but appears to be quite controversial. Information produced as a core public task ("which is nowhere defined clearly") is public.

Really, when will government policy help the questioner push his employer into using structure? Interesting. I don't think we'd get that question in the U.S., other than in the negative.

Conferences here are so civilized, with the opening session at 10 a.m. Ahhhhh. Tea and cookies, er, biscuits at the breaks. Luvely.

Labels: conferences, web 2.0, xml, xpubs

7:39 AM Permalink | |

 

Coming attractions

Saturday, May 10, 2008 — posted by Sarah

I greatly enjoyed my time in Vancouver for DocTrain West.

Unfortunately, the process of getting to and from Vancouver is shaping up to be one of the "typical" travel nightmares. Outbound, I missed a connection (because of weather) by a few minutes, which resulted in a six-hour penalty in travel time.

Inbound back to RDU, I'm writing this on the Vancouver to Dallas plane, which is currently parked at the gate in Vancouver and shows no signs of departing anytime soon. Now, I'd prefer that they fix the hydraulic leak before we go, but it seems as though lately, the on-time rates have gone south. (Hmmm. I live in the South and it occurs to me that this metaphor is a bit locale-ist.) let's try again...the on-time rates have gone down the toilet. (oops. That's sure to offend someone and also lead to Google search hits I'd prefer not to have.) ....the on-time rates really s*** (this is getting worse instead of better). ...the airlines appear to be having some challenges (cough, cough) with their already lousy on-time operations. [Update: We departed almost three hours late with a new, non-leaking hydraulic component.] [Update2: I'm posting this from DFW.]

Anyway, I assume I'll get back at some point. Meanwhile, the conference itself was fun. Got to catch up with lots of people, saw some interesting presentations, and did two sessions that seemed to go reasonably well.

This is only the second time I've done a hands-on workshop in a conference context. Attempting to do one of these sessions is right behind high places, spiders, and eggplant on my list of phobias.

Why? I have little or no control over installation and configuration issues. For an XSL workshop, the minimum requirements are a Java runtime and an XSL parser (both free and open source and therefore a bit challenging to install). A text editor intended for programming (such as Oxygen) would be nice, too. It's impossible to get everyone configured ahead of time, so we end up scrambling to make everything work at the beginning of class. And then we have essentially infinite possible problems ranging from problems with wireless connections to platform variations to security problems (as in, you can't install anything because IT has locked your machine down).

This time around, things actually went extremely well. We had the usual issues, but everything got resolved (which isn't always the case). Although I had rather a large group for a hands-on session, we stayed on track with the schedule and even crammed in some extra material. (Private note to participants: Sorry about the exploding brain problem.) My favorite "problem" in this workshop was in attempting to help one participant. I started typing something and got unexpected input, which was because my touch-typing doesn't work on a non-U.S. keyboard. My attempts to locate the <, >, :, and = keystrokes were truly pathetic. The keyboard owner was nice enough not to laugh at me as she pointed to the correct keys.

Anyway, I'll be attempting this particular trick again at the upcoming Trends in Technical Communication (STC UK) event in Birmingham, so if you're interested in a fun-filled day of declarative programming, you should join us!

After Birmingham, I'll be attending X-Pubs in London. At that conference, I'm presenting the live version of our Web 2.0 white paper. We are attempting to provide some insight into how technical communication and user-generated content will intersect.

If you'll be at either of these events, please let me know.

And finally, after a nudge from a coworker, I have set up a Twitter account. You can find me at okeefe_scr. I'm not sure where that experiment will go, but I thought I'd give it a try.

Labels: conferences, doctrainwest08, travel, web 2.0

6:20 PM Permalink | |

 

DocTrain: Social Media 101/Now Everyone's a Technical Writer

Thursday, May 08, 2008 — posted by Sarah

Darren Barefoot, "recovering technical writer"
Capulet Communications

User-generated content is not new...Shakespeare's Globe Theatre was reconstructed based on a sketch made by a random Dutch person who attended a play at a contemporary theater and drew a sketch.

Most of human history is "few-to-few" communication. Humans sitting around the camp fire and grunting.

Then came broadcast media: "few-to-many" communications.

But now, we have "balkanization" and "diversification." The model is now "many-to-many" communication.

(I have a very similar discussion in our Web 2.0 white paper. Link below.)

Free and cheap tools (blogging software, cheap digital cameras) have made "many-to-many" communication possible. This is sometimes called the "rise of the creative class." People are shifting from being consumers to creators.

Seven concepts that differentiate social media:

• conversation...two-way communication rather than a broadcast model
  
• collaboration...obvious example is Wikipedia
  
• sharing...micro-broadcasting, perhaps just to family and friends
• scope...column inches and 42-minute hours on television are gone. Tools are easy, distribution is easy; don't need to be constrained by traditional approaches.
  
• Community...we are constructing affinity groups, which can be "thin-sliced." Can gather together in ways that were never possible before because geography is eliminated as a constraint.
• Transparency and authenticity...blogging and social media tend to encourage these. However, both of these are perhaps problematic. Examples: LonelyGirl and FakeSteveJobs. Perhaps these are less critical than before?
  

Social media components (the usual):

• Facebook
• RSS
• Brightkite
• Twitter
• FriendFeed
• Video Streaming
• StumbleUpon
• Blogs
• virtual Worlds
• Social Bookmarking
• Flickr
• Ning
• Mashups
• and more

Who make social media? "the people formerly known as the audience"

Why do people blog?

• Talk to friends and family
• keep personal history
• emote
• experiment with technology
• practice writing
• make change
• follow trend
• and more

Corporate blogging is a tiny slice of social media.

Great video on Wikis in Plain English

More examples of social media being used for technical documentation tasks.

Very interesting presentation, with quite a bit of intersection with our Web 2.0 white paper (PDF, 1.7 MB). (Sorry to keep linking to it, but this is clearly the current hot topic.)

Labels: doctrainwest08, web 2.0

1:44 AM Permalink | |

 

DocTrain: Bringing the Video Revolution to Technical Communication

Wednesday, May 07, 2008 — posted by Sarah

RJ Jacquez of Adobe
Senior Product Evangelist, TechComm Suite and e-Learning initiatives

(This is the first time he has presented this content.)

There are now four generations in the workforce; the youngest belong to Generation Y, the "video generation," born between 1981 and 2000. This generation assumes use of the Internet and technology such as picture phones, iPhone, email, instant messages, blogs, podcasts, social networking and bookmarking, tagging, wikis, and Second Life.

Adobe is organizing the first-ever Virtual Trade Show -- a conference on e-learning (!) that will take place entirely online with no offline equivalent. They're calling it the industry's "first true desktop trade show." It will take place in Second Life or something similar.

Internet video is growing explosively:

• 9 billion video clips available.
  
• 134 million users have watched video online.
  
• 75% of US Internet users watch videos online.
  
• 181 minutes per viewer per month.
  
• 68 clips per month

RJ believes that people are expecting their documentation support to be delivered in this medium. They are looking for screencasts or short videos to help them. Adobe TV, which has instructional content for design professionals, is now delivering high-definition TV on the web.

95% of online video traffic is Flash-based.

Adobe is claiming widest "reach" in the world -- 250 million PDF files on the public web and 98% installation rate of Flash Player. He's also put Adobe AIR on this slide, presumably because they would like for it to become the next standard.

Nice demo of PDF with 3D. The example is a brake assembly. Being able to manipulate the model is kind of fun, but the ability to remove pieces of the brake assembly part by part is really useful. The page has a series of buttons that let you specify which parts you want to remove. You can see the demo file here.

Demo of PDF with animation. Very nice. We have an example of this in our Web 2.0 white paper, available here (PDF, 1.7 MB).

And now Adobe AIR. His example is Buzzword help.

(Side note: RJ likes the phrase "really, really cool.")

Labels: adobe, doctrainwest08, web 2.0

11:47 AM Permalink | |

 

White Paper 2.0

Monday, April 14, 2008 — posted by Sarah

We have just posted a new white paper, Friend or Foe? Web 2.0 in Technical Communication (PDF, 1.7 MB). The abstract:

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, whereas technical documentation is
comprehensive but less 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.

We hope to have an HTML version available soon so that we can actually practice what we preach. Meanwhile, please leave your comments in this post.

PS I'm also interested in comments on our new white paper format and our use of Flash animation.

Labels: web 2.0, white papers

2:42 PM Permalink | |

 

Good advice for system admins and technical writers

Friday, March 14, 2008 — posted by Alan Pringle

A recent article offers tips for system administrators to be competitive in today's job market. A lot of the suggestions apply to those in the technical writing field, too.

The following point is worth repeating because I have forgotten it myself in the heat of deadlines:

Customer service skills. A system administrator (or system admin) constantly interacts with people, responding to their problems (and resolving them), and attempting to keep the customer happy. Make no mistake -- these are your customers, even if they are in the same company.

Substitute "tech writer" for "system admin" and "end user" for "customer" in the example, and you have a very useful piece of advice. Interacting with end users--internal or external--is essential to ensure that documentation is as useful as it can be.

Because of tight schedules and resource problems, I think it's really easy to get into a bunker mentality and basically shut down contact with the outside world to crank out deliverables. Unfortunately, that's among the worst things you can do: isolating yourself from useful feedback just perpetuates problems in documentation, many of which you may not have anticipated because you are too familiar with the product.

Companies are beginning to use Web 2.0 technologies in their documentation processes, though, and that enables instant feedback from users. (BTW, Sarah is presenting on this very topic at the WritersUA conference in Portland, Oregon, next week. I'll be there, too.)

All this being said, sometimes your external customer (the end user) wants something different than your internal customer (your management). Balancing these competing requirements can be difficult, to say the least.

Labels: web 2.0

3:13 PM Permalink | |

 

XFL: He Hate Me Not

Saturday, March 08, 2008 — posted by Sarah

(For those of you with a life, the title is a reference to this.)

According to Colin Moock, the next version of Flash will have an XML-based format. He writes:

Flash CS4 will be able to export *and* import a new source format called XFL. An XFL file is a .zip file that contains the source material for a Flash document. Within the .zip file resides an XML file describing the structure of the document and a folder with the document's assets (graphics, sounds, etc). The exact details of the XFL format are not yet available, but Richard [Galvan, Flash authoring-product manager] assures me that Adobe intends to document them publicly, allowing third-party tools to import and export XFL.

This is important. Currently, it's fairly impossible to integrate Flash and non-Flash content. Other than, of course, with our 80s friend, Mr. Cut-and-Paste.

If Flash speaks XML, we can develop a process along these lines:


(h/t John Nack)

PS "Carolina Goodnight"? I don't think so. See note 4.

Labels: web 2.0, xml

8:13 PM Permalink | |

 

2008 Predictions: They'll keep me humble in 2009

Wednesday, January 02, 2008 — posted by Sarah

Each year, I write up an internal annual report, which discusses company performance in the previous year, looks at trends, and lays out a strategic plan for the following year. Generally, this report looks great in November and December and is completely obsolete by March (at the latest). Nonetheless, I thought I'd share some of the highlights from this year's analysis. I hope you will share your agreement or disagreement in the comments.

No clear leader for DITA
DITA authoring tools are everywhere. Long-time contenders (FrameMaker, Arbortext, and XMetaL [anyone remember SoftMetal or HotMetal??]) are adding DITA feature support. Many help authoring environments are adding DITA import or export. Several companies are developing web-based DITA authoring tools, and In.Vision Research has a DITA authoring plug-in for Microsoft Word.

The tools proliferation is disconcerting. In the olden days (the early 90s!), serious technical publishing was a fairly easy choice among FrameMaker, Interleaf, and maybe Ventura Publisher. Now, some tools are on the desktop, some are in the browser, some reside inside other tools, and life is much more complex.

Will things look different in five years? Certainly. I doubt, however, that we'll be back to half a dozen (or fewer) contenders. Instead, I think DITA output will become a check-off in the same way that HTML output is now.

Reuse analyzers
Both MadCap Software and Author-It have developed reuse analysis software -- Analyzer and XTend, respectively. Most of us are familiar with translation memory tools, which try to match new content to be translated against existing content in the TM database. The reuse analyzers do similar work, but in the source language. As you write, the software compares new content to existing content and recommends matches.

This is such an elegant, obvious idea that I can't believe it's new. But I haven't seen this type of tool in desktop-level software before.

Web 2.0 integration
User-generated content, such as blogs, wikis, and forums (not to mention YouTube), is on a collision course with "professional" content, such as user assistance and documentation created by technical writers. The complaints about the amateurs butting in where they don't belong must be painfully familiar to those who remember the rise of desktop publishing software and the destruction of the vast majority of the professional typesetting business.

Note: I laid out my first magazine in PageMaker. Version 1. What little manual paste-up I did was not very attractive.

Note to young people: The expression "cut and paste" is used because in the olden days, your parents used to use scissors ("cut") and glue ("paste") to move things around on a page layout. And "strippers" didn't always use poles. But I digress...

People who are paid to create technical content need to understand what user-generated content will and will not do. (Shameless plug: I'm doing a session on this topic at WritersUA in Portland, OR, this year.)

Global business
We have our fair share of customers in North America, but an increasing number of our clients are outside North America or have significant operations in multiple locations around the world. The implications for technical communicators are global audiences, global customers (internal and external), and a requirement to work well with people from all over the world.

This is an area where I believe that U.S. communicators face some significant challenges.

Flash
I expect Flash to become the next Next Big Thing. Flash technology enables the creation of interactive applications that run in a browser (or offline with AIR, which is also fascinating). Flash is widely used for games, but for our purposes, its role in e-learning applications is more important.

Traditional classroom training is effective (when you have a good trainer), but it's also expensive and it doesn't scale well -- the more people need training, the more costs rise. And furthermore, if the students are scattered literally all over the world, the costs of assembling them all in one location are astounding. I firmly believe that e-learning is less effective than a great classroom experience (of course, I'm biased since I am an instructor myself), but e-learning has some significant advantages -- like eliminating travel requirements and reducing overall cost.

Flash has almost nothing in common with the current Next Big Thing -- XML. XML is markup, text, human-readable, and geeky. Basic Flash is like Illustrator with an extra dimension (time). Advanced Flash is an application development environment.


So there you have my list of important developments for 2008. Do you agree? Disagree? Have additions?

Labels: analysis, dita, web 2.0

2:07 PM Permalink | |

 

It's the time of the season for...

Thursday, November 01, 2007 — posted by Sarah

...conferences?

I'm finishing up my slides for next week's tekom/TCWorld conference (don't tell the organizers). Meanwhile, registration for next year's WritersUA conference has just opened. It will be held in mid-March in Portland, Oregon.

As usual, Joe has put together a great program. Zip on over, take a look, and start working on your funding.

I will be doing a session in the Emerging Skills track entitled, Friend or Foe? The Role of Web 2.0 in User Assistance.

May and June 2008 are already stuffed with conferences. It's a little odd to look at my calendar and realize that I had better start thinking about where to put my summer vacation.

Labels: conferences, web 2.0

2:28 PM Permalink | |

 

The Age of ... Expertise?

Wednesday, September 05, 2007 — posted by Sarah

Over on O'Reilly's Radar blog, Andy Oram has a fascinating article about the demise (!) of the Information Age and what will be next:

[T]he Information Age was surprisingly short. In an age of Wikipedia, powerful search engines, and forums loaded with insights from volunteers, information is truly becoming free (economically), and thus worth even less than agriculture or manufacturing. So what has replaced information as the source of value?

The answer is expertise. Because most activities offering a good return on investment require some rule-breaking--some challenge to assumptions, some paradigm shift--everyone looks for experts who can manipulate current practice nimbly and see beyond current practice. We are all seeking guides and mentors.

What comes after the information age? (be sure to read the comments, too)

It's an interesting idea, but I don't think we're getting away from the Information Age into the Expertise Age. After all, expertise is just a specialized (useful!) form of information.

In the comments, Tim O'Reilly points out that the real change is in how information is gathered and distributed with "the rise of new forms of computer mediated aggregators and new forms of collective curation and communication."

I believe that we are still firmly in the Information Age because information has not yet become a commodity product. There is, however, clearly a shift happening in how information is created and delivered. I think it's helpful to look at communication dimensions:

• Traditional technical writing is one-to-many. One person/team writes, many people consume it.
• Wikis are many-to-many. Many people write; many people use the information.
• Mailing lists are many-to-one. Many people respond to one persons' question.
• Technical support is one-to-one. One person calls; one person responds.
  

Technical support is the most expensive option; it's also often the most relevant. Technical writing is more efficient (because the answer to the question is provided just once), but also less personal and therefore less relevant.

Many technical writers are concerned about losing control over their content. For an example of the alarmist perspective, read Joanne Hackos's recent article on wikis. Then, be sure to read Anne Gentle's eponymous rebuttal on The Content Wrangler.

Keep in mind, though, that you can't stop people from creating wikis, mailing lists, third-party books, forums, or anything else. You cannot control what people say about your products, and it's possible that the "unauthorized" information will reach a bigger audience than the Official Documentation(tm). You can attempt to channel these energies into productive information, but our new information age is the Age of Uncontrolled Information.

Furthermore, the fact that people are turning to Google to find information says something deeply unflattering about product documentation, online help, and other user assistance. Why is a Google search more compelling than looking in the help?

Labels: change management, web 2.0

1:29 PM Permalink | |

© 2009, Scriptorium Publishing Services. Legal Stuff