The world of technical content

The functional goal of technical content is to help people use a product successfully. The business goal must tie the content into organizational strategy. For instance, in a regulated industry, creating required documentation is a prerequisite to entering the market.

Technical content may have persuasive objectives; for example, describing the additional features available in a more expensive product edition and thereby encouraging people to upgrade. But the informational angle is more important than the persuasive function. Persuasive content is marketing content, where the primary goal is to convince the reader to buy a product or service. This difference in perspective separates the practices of technical communication (tech comm) and marketing communication (marcom).

Perhaps Tim O’Reilly, founder of O’Reilly Media, says it best. Technical information is “changing the world by spreading the knowledge of innovators.”

But not all technical content contributes to this mission. Most everyone has attempted to decipher a manual or support web site that uses incoherent language, atrocious organization, and appalling formatting. These information products are unusable because the responsible organization does not believe that technical content quality affects business performance. But is this true?

When managed properly, technical information can help you to:

  • Meet regulatory requirements with minimum cost
  • Extend your global reach by delivering content optimized for each market
  • Reduce technical support costs
  • Reduce product returns
  • Improve customer satisfaction
  • Lower the overall cost of information development

Historically, tech comm has been a cottage industry where each technical writer is responsible for a specific content area. Today, tech comm is moving into a manufacturing model. This approach requires a huge shift in mindset for experienced writers. Instead of owning all aspects of a book or help system, writers become content contributors who collaborate to produce a final product. This approach has advantages for the organization, especially for larger writing groups, but it is highly disruptive to the traditional approach because of the following factors:

  • In traditional tech comm, a writer is responsible for a defined information product, usually from start to finish. That means developing an outline, creating the content, and formatting it for the final delivery (such as PDF or HTML). In a collaborative approach, a writer might have an assignment to write just 25 percent of a document and have no input on the final document presentation. It is the difference between hand-crafting an automobile and working on a specific component on an assembly line.1
  • Writing in a collaborative environment is much more difficult than writing solo. The information must be consistent so that content from different writers can be assembled into a coherent document. This requires strict adherence to style guidelines and avoiding unique turns of phrase that stand out from the larger document.

Most managers and executives treat technical communication as a cost center. Content Strategy 101 focuses on how to evolve technical information from “necessary evil” to “business asset.” Some examples of this transformation include the following:

  • Improve content by removing extraneous information (“minimalism”), which results in reduced development and localization costs.

  • Improve templates and formatting automation, thus reducing manual formatting time in each product release.

  • Use search engine optimization techniques to improve content’s Google performance, increasing page views and therefore visibility of your content. (Then, show a correlation between increased web site traffic and reduced technical support calls.)

  • Ensure that information is shared across the organization, so that different groups do not waste time writing the same content twice.

For technical communicators and consultants, a stronger focus on business value means that they must:

  • Have a reasonable level of writing competence. In most cases, an adequate writer who produces content quickly will be preferred over a great writer who works more slowly.

  • Produce content that conforms to established style guidelines, templates, and other corporate standards. (Clean content is more valuable than messy content.)

  • Look for ways to improve productivity and drive down the cost of content development infrastructure.
  • Focus more on efficient technical communication and less on the art of writing. For example, they might develop innovative new ways to create and deliver content, such as increased community participation.

Competing priorities

Some technical writers see themselves as user advocates—they identify with the user who needs help using a complex product. The “user advocate” perspective needs to be balanced with the business priorities. Technical communicators are paid not by the user, but by the organization, and that means focusing on business value and not purely on users. The most egregious offenders wield “the user” as a club to justify their personal style and content preferences.

The technical communication group is not the ombudsman for the user. Close collaboration with product developers is needed instead of an antagonistic relationship based on the product developers’ perceived lack of empathy for the end user.

A successful content strategy for technical content must balance the following, often conflicting, issues:

  • Strategic. Technical content must support business goals. If certain information is required in the documentation to meet legal requirements, it must be included even if it is not useful to the reader. If the goal of technical content is to support marketing, some persuasive information is appropriate.
  • Useful. Technical content must provide readers with the information that they need in an appropriate format.
  • Efficient. The process of creating technical content should use limited resources wisely.

Balancing competing priorities is essential for successful technical communication

For a summary of the components that contribute to good technical content, see Appendix A, “Creating useful information.”

 

An overview of content delivery options

Here is a quick overview of some of the most common formats used to deliver technical content.2

Paper
The only option until the 20th century provides a huge variety of items ranging from art books (“coffee table books”) to laminated quick reference cards. In technical communication, printed information products are increasingly rare because of cost considerations. Paper is used mainly in locations where electronic deliverables are not technically feasible, such as mines, deserts, and other remote locations, or disallowed by policy, such as many retail organizations and secure facilities (government, utilities, and others). Books are perceived as having high value, so including an attractive book with a product helps the positioning.
Portable Document Format (PDF)
PDF files are an electronic substitute for paper documents. A recipient of a PDF file can print the file and get a fully formatted document that matches the paper that used to be shipped. This is the most common use of PDF files—as a substitute for shipping paper documents. Instead, the cost of printing is shifted onto the recipient, and the time and expense of distributing paper copies are eliminated. PDF files provide some enhancements over paper books, including full-text search, support for 3D images and animations, and live links. PDF files, however, tend to be large and hard to manage.
Web sites
Web sites are another broad category that encapsulates a huge range of content. For technical content, the most common approach is to offer a dedicated site for the documentation (often with a subdomain like docs.example.com) and to provide search capability for the content. Many organizations use the web for content distribution but provide only PDF files and not HTML versions of their technical content. Web sites can be available to the general public or restricted to users with varying levels of credentials required. Only sites that are available to the public are indexed by public search engines.
Multimedia tutorials
Multimedia tutorials are short videos or screencasts (animated screen shots that show a user working in a software application), usually with a voiceover or captions. Tutorials are useful for explaining complex tasks (such as machine repair) and complex software interfaces.
Ebook formats
The ebook landscape is still in flux. The two important formats are currently EPUB and mobi. EPUB is a standard storage format maintained by the International Digital Publishing Forum (IDPF).3 The iOS iBooks reader and Barnes & Noble Nook support EPUB files. The other format, mobi, is used by Amazon Kindle devices and other ereaders. Amazon’s proprietary AZW format is a compressed mobi file, and KF8 format (also proprietary to Amazon) includes mobi and EPUB in one file. In general, technical ebooks are seen as a replacement for print or PDF files. An “enhanced” ebook could go beyond a basic paper replacement and offer interactivity to take advantage of the ereader’s capabilities.
Online help
This category includes compiled help (such as Microsoft HTML Help) and “web help,” a general term for help that is presented in a web browser (rather than a dedicated help viewer). Typically, web help includes a navigation frame on the left for table of contents, index, and search (often called “tripane help”) and a content frame on the right for information. The tripane approach, however, is rapidly going out of fashion because of problems on mobile devices. The term “online help” is showing its age—it refers to help on a computer (as opposed to on paper) and not necessarily to help that is on the Internet. Online help can be embedded with software, shipped on a CD, or delivered over the web.
Knowledge base
Knowledge bases are most often used by technical support organizations. They are intended for articles, such as explanations of unique configuration problems, that are created by technical support staff as they provide phone- or email-based assistance.
Forums
Discussion forums and bulletin boards predate the Internet. The conversation can be raucous at times; for corporate forums, it is critical to establish and enforce ground rules. That said, a heavy-handed moderator will drive participants away to less-restricted venues. Too little moderation will drive away participants who do not want to wade through personal attacks and irrelevant political postings to find the information they need.
Wikis
A wiki is a web site whose content can be edited collaboratively by its users.4 The most famous example is Wikipedia (wikipedia.org). Many organizations provide advanced technical content in wikis and let customers comment on it or edit it. Wikis are most appropriate for detailed content that goes beyond the basics and changes rapidly. Examples might include code examples for a programming language. Wikis are used heavily in user-generated references for online games.
1 For a detailed exploration of this idea: “You can have any color, as long as it’s black,” Dr. Tony Self, first published in ISTC Communicator, Spring 2012, (hyperwrite.com/Articles/showarticle.aspx?id=90).
2 “Key Trends in Software User Assistance,” Joe Welinske, 2012, writersua.com/articles/keytrends/index.html
4 Source: Google search for “define:wiki,” accessed August 13, 2012

 

One Response to The world of technical content

  1. Pingback: Making the Technical Article Accessible - Kevin M. MitchellKevin M. Mitchell

Leave a Reply

Your email address will not be published. Required fields are marked *

Navigation