Technical Writing 2.0

— Suranjana Das Gupta

Purpose

You've heard about Web 2.0 and the revolution that it heralds. Now, does technical writing need to change its version number in order to keep up with the changing environment? This white paper tries to find the answer to this question.

Overview

"Tech Writing 2.0" is a term coined by Ellis Pratt of Cherryleaf for the application of Web 2.0 technologies to technical documentation. "Tech Writing 2.0" is a move away from static, broadcast, documentation to more participative and aggregative information resources.

Concept

What do we mean by Tech Writing 2.0?

Tech Writing 2.0 is an application of Web 2.0 services and technologies to technical communication. Web 2.0 gives us the opportunity to change significantly the quality of what the users receive.

This new wave is not about the introduction of DITA or the introduction of the new Help format in Windows Vista. These two technologies will mainly affect what happens behind the scenes. What the user receives is unlikely to change much from what they receive today.

What do we mean by Web 2.0?

Wikipedia defines Web 2.0 as: "A second generation of services available on the World Wide Web that lets people collaborate and share information online. In contrast to the first generation, Web 2.0 gives users an experience closer to desktop applications than the traditional static Web pages."

Within Wikipedia's definition, there are two themes:

  • Devolving content creation to the users (i.e. collaboration on content creation and sharing of knowledge)
  • Providing a "rich user experience" (i.e. making Web applications feel more like desktop applications)

Another way of answering that question is to look at sites which people have called Web 2.0 sites. These include sites such as Lulu.com, Blogger.com, Flickr.com, Newsgator.com and Technorati.com. Within these we can see three common elements:

  • Collaboration on content creation
  • Conversation (wisdom of the crowd)
  • Aggregation of knowledge

Web 2.0

Web 2.0 may not have an exact definition everyone agrees with, but few will dispute that in part, it means building features into your site or application that allow users to become contributors to the content. The degree to which users can contribute defines the level on the Web 2.0 scale. For the most extreme applications, the entire content is driven by users. In other instances, users may contribute only a little, but this contribution still becomes part of the site or application’s appeal.

Common Web 2.0 Features

One of the basic requirements of Web 2.0 is user interactivity. Web 1.0 was all about static Websites and treating the user as a reader only. Web 2.0 allows the reader to interact with the content, and more specifically, to add to the content. The result is, as O’Reilly calls it, collective human intelligence that outperforms anything a single individual can do.

Basic features might include the ability to:

  • Comment on the content
  • Rate the content
  • Sort by different ratings (highest ratings, most rated, most searched, etc.)
  • Edit the content
  • Add to the content (text, photos, video, voice)
  • Integrate the content with other applications
  • Automatically generate profiles that others can learn from, listen to, or read Help 2.0

So how can we apply the principles of Web 2.0 to our help documentation? This is the question we must answer to move help content into the next generation of the Internet.

Creating Help in the Web 2.0 Age

When many of us first became aware of the Internet, we associated “surfing” with visiting a variety of sites, scanning through pages for information, and just as one might surf the television, we browsed and skimmed through content located at a variety of destinations. The metaphor of “surfing” the Web is quintessentially what Web 1.0 was all about. Web 1.0 relied on the idea of content being housed somewhere, and we used our computer to visit these places where the content lived, viewed it on our screen, and then moved on to other places. Designers and technical communicators in the Web 1.0 era were trained to create and fill these “places” with content situated within the space, and constrained both visually and rhetorically by their locations.

Web 2.0 is a movement away from understanding content as housed in Websites and instead views content as “granular.” In this way, the content can be syndicated and distributed in decentralized ways and without relying on the user visiting a site or
page in order to find the information or content. With the advent of Web 2.0, or the Web as platform, not place, technical communicators and designers will need to rethink many of their strategies regarding how their writing works in relation to “place”.

The Web 2.0 movement focuses on the Web as a “platform” where already existing products, tools, or data are combined in ways that move beyond their original intentions. Whereas Web 1.0 focused on the location of information, products, or tools as located at a specific URL, Web 2.0 focuses on data in a syndicated format. For example, multiple interfaces, with multiple rhetorical purposes, can all be built upon the same set of syndicated data.

MacManus and Porter, in “Web 2.0 for Designers” give the example of amazon.com, whose database of content is made available for anyone to remix. “Anyone can design an interface to replace Amazon’s to better suit specific needs (see Amazon Light)”. The power of this type of syndication is that content can be remixed to suit multiple rhetorical contexts, many of which may never have been intended nor imagined by the original content creators or distributors.

Associated Press CEO Tom Curley has argued that “… content will be more important than its container in this next phase [of the Web]… Killer apps, such as search, RSS and video-capture software such as TiVo—to name just a few—have begun to unlock content from any vessel we try to put it in.”

Interfaces, such as Grassroots, use the Google Map API to create new programs. These mash-ups are quintessential Web 2.0.

For content to reach the types of syndication and distribution imagined by Web 2.0 enthusiasts, content needs to break free of the containers that both bind it and display it. One of the most significant ways that this transition to Web 2.0 can be seen is in the move toward XML, and semantic markup. With this move toward the granulation of content, however, technical communicators need to rethink how to present content. “Because content flows across the Web in RSS feeds and can be remixed along the way, Web designers must now think beyond sites and figure out how to brand the content itself.”

For years, technical communicators have created help on a mass industrial model—one finished help system for all users. But two technologies, XML and Web 2.0, offer ways to change that model, letting us create just-in-time help personalized to specific user-needs, with content written by users themselves.

Flare—an authoring tool using XML—lets us automatically create help systems that reflect the needs of specific sets of users, possibly even specific users, when those users request help. In the case of Web 2.0, we get the flexibility to let end users create content themselves, taking some of the load off technical communicators.

This all sounds futuristic and idealistic, but the automatic Flare output has already been done on a test basis, and user-contributed content is all around us – in Wikis, for example.

Help 2.0 is what might be called Web 2.0 applied to help documentation. We are becoming used to seeing Websites equipped with Web 2.0 features, and it’s only a matter of time before the technical communication community catches up and begins integrating the same features.

How Can We Apply Web 2.0 to Technical Communication?

Let's think about what Web 2.0 could mean to technical communicators. Not everything that comes under the banner of Web 2.0 impacts the documentation world. Some of the techniques and technologies, however, can be used by technical authors to improve their documentation and the experience of those using it. It could allow you to:

  • Gain a greater understanding of the issues users face. You can involve your customers in development, gather intelligence, and sustain a constant dialogue. You can promote conversations between members that build trusted relationships, self-help and support teams, bodies of knowledge, special interest groups to name just a few.
  • Provide better support. "The wisdom of the crowd" can emerge—the community members create new ideas and provide practical solutions for other members.
  • Sell "value added" support information for a fee.
  • Gain greater customer loyalty and trust.

Today, it can be very difficult to incorporate content from third parties. In most situations, writers have to resort to "cut and paste", taking content from one document and pasting it into the master document. Writers find themselves spending considerable time modifying the formatting and structure so that it conforms to the rest of the document. They rarely have the power to dictate the structure and formatting to others. Collaborative publishing means projects where documents are created by many different people working together (collaboratively) rather than individually.

Web 2.0 offers a variety of ways to write collaboratively. These ways might:

  • Be used as the principle authoring environment for documents.
  • Be integrated into a unified documentation set.
  • Sit alongside the "official" documentation.

Implications for Technical Communicators

As writers, we have long been taught to consider the means of delivery of a piece of writing as a fundamental component. That is, the medium is the message. But with the advent of syndicated content, the writers will have less influence over the medium in which their content will be used. In this way, Web 2.0 represents a possible paradigm shift in how we view writing, as well as in how those who hire technical communicators view the work that we do. In many ways, designers and writers in the Web 2.0 era will need to think more like programmers.

One of the most potentially exciting pieces of the Web 2.0 movement is that the users of the information will have far greater control in accessing, influencing, and remixing information for their own use. Granulated content means that users can choose to bypass many of the “places” on the Web where that content was generated.

A technical communicator’s work of composing syndicated data will require that the writer understand the ways in which the “social web” can and will remix, search and tag their information, which can already be seen in certain applications such as del.icio.us and Flickr, as well as the numerous mapping interfaces, such as
Grassroots that rely on the users creating new interfaces with Google map's API. In the era of Web 2.0, the users will not only have a great deal of control over the information they see, but they will also be consistently generating metadata, new interfaces, and new content, from that which is supplied to them.

“The effects of Web 2.0 are far-reaching. Like all paradigm shifts, it affects the people who use it socially, culturally, and even politically. One of the most affected groups is the designers and developers who will be building it—not just because their technical skills will change, but also because they’ll need to treat content as part of a unified whole, an ecosystem if you will, and not just an island” (MacManus and
Porter).

In conclusion, as MacManus and Porter argue, the major elements technical communicators will need to consider in regards to the Web 2.0 movement include: the rise of XML and semantic mark-up (which allows for the easy syndication and granulation of information), the rise of the social Web and the user’s role in creating metadata, the movement for technical communicators and designers to think and act more like programmers, and for the movement away from Web as a place to Web as a platform.

The “Ultimate” Help

This is what the “ultimate” help application would have:

  • Users can rate help topics according to their usefulness. The highest rated topics are automatically aggregated into one section. The lowest rated topics are aggregated in another section and flagged as “needing help.”
  • Users can add comments to the help topics to identify problem areas or to suggest tips or other ways of going about a task. Users can comment on the comments of other users—in other words, the comments aren’t just emails sent to the help team. They are publicly available comments that other users can respond to.
  • When a user wants to contribute a help topic, the submission form is coded with behind-the-scenes DITA tags. The content that users enter can be transformed into usable documentation without a technical communicator needing to reformat it.
  • The content is semantically rich and accessible because the DITA tags enable semantic Web search (e.g., search operations only for calendar events, or only for help content).
  • Users can construct their own help manuals. They open up a page that shows the table of contents in the left column, and a blank column on the right. They can then drag over the topics they want to print. These topics are compiled automatically and printed.
  • When users search for topics, the search engine gets smarter depending on the users’ selection of the results. Search returns that are selected more often move up in the list of returns.
  • The help system incorporates trackbacks, so that when people write posts about the application on their own sites, their comments are shown in the help system in a unique location.
  • The product has an RSS feed that integrates into the help file of the application. The RSS feed is the blog of the development team, so users can be aware of what’s in the works, what the team is having issues with, what enhancements are available, tips, etc. Help is no longer a static entity hard- coded and shipped with the application. It is a continuously living file that changes dynamically depending on new information.
  • The help application is open-source, and you can add plug-ins to it to extend its functionality. You don’t have to wait until the company issues a next release. Instead, you can incorporate new plug-ins that extend the application’s functionality on the fly. If you don’t like something, you can enter the code and change it. You can also re-release your code and make the changes available to others. In this way, developers build on the development of other builders.
  • A user-live view is available in the help file. Administrators can watch the mouse-movements of users in real-time as they manipulate the help file, making selections and clicking aimlessly. Statistics are compiled that show graphs of the popularity of different topics. You can even incorporate Google Analytics to view the hotspots of user clicks.
  • Youtube videos are integrated into the application walking the user through different procedures. The Youtube videos can be created by anyone—the help file just incorporates videos continuously based on keywords that pull in content from a Youtube feed. The videos are narrated by both experienced and amateur voices.
  • Users desiring to participate in user-research can turn on their webcams and participate in user-research. This feature would be integrated with the live view plugin that allows administrators to view user activity in real-time.
  • The content can be exported to mobile devices and be called upon on video iPods when the user needs to figure out instructions on site.

The shortcomings of such a system are probably manifold. Traditional help authoring tools offer so many advanced features that blog/Wiki type applications don’t have.

But eventually the two will marry each other, and help will move forward.

Bibliography

About the Author

Suranjana is the location practice lead for the Technical Communication practice of the Content and Design Services group of Cognizant Technology Solutions. She has 10 years of experience in putting together end user, system, and process documentation.

You can reach Suranjana at suranjana.dasgupta@cognizant.com or sdas_gupta@hotmail.com.

STC India | Home | Contact Us

Copyright © 2008 India Chapter STC. All rights reserved.