Applying Web 2.0 Technologies to Technical Documentation

This article is based on my presentation at the Institute of Scientific and Technical Communicators' annual conference in October, 2006. Every now and then, there is a change in the value of what technical authors deliver. These are moments when organisations pay attention to technical documentation. This is because they recognise that these changes mean they can create something that will be of real value to the business and to their customers. In recent years, there have been three "waves of interestingness". The first wave was the introduction of Windows Help (WinHelp). The second major wave was the introduction of the Internet and intranets. This was a time when organisations looked at how they could transfer large amounts of information from paper to online. They were faced with issues such as how users could access and understand all this information easily - issues that technical communicators deal with on a day-to-day basis. I believe we're just about to approach the new wave, which we have called "Tech Writing 2.0".

Pratt, Ellis. Cherryleaf (2006). Articles>Web Design>Documentation>Technical Writing

Are We Giving Readers What They Want, in the Way They Want and Need It?

With all the talk about Web 2.0 and the attendant technologies, are readers actually being better served by documentation now than they were in the past?

DMN Communications (2008). Articles>Documentation>Technical Writing>User Centered Design

Conciseness is Key to Good Technical Documentation

One of the most important and difficult parts of technical documentation concerns writing in a concise manner. Technical writing is different than writing fiction or magazine articles, where a mood may be set or--in some cases--where space must be filled. (People seldom buy thin books.)

Kurtus, Ron. School for Champions (2005). Articles>Document Design>Technical Writing>Minimalism

Creating User-Friendly Documentation

We often hear that users do not read documents. To lure readers into reading our documents, we must make documents user-friendly.

Bhatia, Neeraj. Indus (2002). Articles>Documentation>User Centered Design>Technical Writing

Equations

Equations must have a number in parentheses at the right of the page. Must be numbered in the order they appear. Must be able to be read as part of the text.

Young, V.L. and K.J. Sampson. Ohio University (2004). Articles>Document Design>Technical Writing>Mathematics

Getting to Expert

The gaps in your documentation aren’t there because you haven’t consider a particular level of user; the gaps in your documentation are there because you haven’t considered how one level of user becomes another. How DO you get from Beginner to Expert?

McLean, Gordon. One Man Writes (2008). Articles>Documentation>User Centered Design>Technical Writing

Heading Frequency and Comprehension: Studies of Print Versus Online Media  

This paper describes a study that examined the effect of heading frequency on comprehension and perceptions of information presented in print versus online text. Results indicated that heading frequency did not differentially affect the comprehension of readers of print text while it did differentially affect the comprehension of readers of online texts who had considerably lower comprehension scores with text that had high frequency versus medium frequency headings.

Spyridakis, Jan H., Laura D. Schultz and Alexandra L. Bartell. STC Proceedings (2005). Articles>Document Design>Writing>Usability

How to Write a Newsletter

Newsletters are one of the least expensive -- and most effective -- public relations tools that exist for drawing attention to a business or Web site. By sending out a quality newsletter on a regular basis, you can keep clients, potential clients, the media, and other important sources updated about your business. Frequency of mailing builds familiarity, and familiarity inspires return visits. Plus, the effort of creating a newsletter itself speaks volumes about your commitment to the subject. It also positions you as an expert and a valuable resource.

Writing That Sells. Articles>Document Design>Journalism>Writing

IBM User-Centered Design for the Documentation Designer  

The user-centered design of documentation is an aspect of product design that has often been under-emphasized. Difficulties inherent in documentation design include obtaining user, feedback to high-level design objectives; extracting user. feedback specific to a product’s documentation. rather than to the product as a whole; and managing the various resource constraints inherent in product development. IBM User-Centered Design offers a solution to these difficulties by employing a set of user feedback methodologies from which the documentation designer, a member of a multidisciplinary design team, extracts pertinent data to set design objectives and follow through to low-level designs.

Righi, Carol and Lynn VanDyke. STC Proceedings (1996). Articles>User Centered Design>Documentation>Technical Writing

Is Your Website Poised to Deal With Its Growth?  

Every webmaster nourishes the dream that his or her website will make it the big way. This is very much human because people carry out any task in ardent hope. What is more human out here is that earthy fellows like us base our aspirations more on speculation rather than specific set of steps undertaken to bring the dream a bit closer to reality. And this is not all, particularly in case of growth of a site which brings newer problems in the wake of its growth. It cannot be disputed that you can probably get some good web hosting on economy price. But if you expect top of the line service on this price, acknowedge gracefully that your are just asking for the moon. Probably you are not catching up with wisdom that business needs decisive investments.

Azam, Rahbre. Amateur Writerz (2008). Articles>Documentation>Web Design>Technical Writing

Producing Brochures in the Technical Writing Classroom  

Producing brochures for real clients teaches college-level technical writing students about constraints of cost, time, and the availability of materials. Brochure writing also provides opportunities for learning more about editing, collaborative work, document design, and the problems which may occur during the production of real documents. Brochures of good quality can be produced by a class in approximately three weeks, or nine classroom hours. Grading brochures is expedited through the use of a simple heuristic.

Ryan, Charlton. STC Proceedings (1993). Articles>Education>Document Design>Technical Writing

Technical Writing in Everyday Life: One User's Experience

The experience of setting up a new home theater system also sharply reminded me of what it is like to look at something as a new user: staring at a bunch of knobs and holes for the first time, holding a tassel of wire in one hand and a manual in the other, and really just wanting the darn piece of ?%^%! to do what it's supposed to do.

Vedrody, Sarah. MetroVoice (2002). Articles>Documentation>User Centered Design>Technical Writing

Has Anyone Used Your Product

Before you release a product, have some people use it. From these "test users" get solutions to problems, tips and knowledge that would help your real-life Users. Put that information in your User Documentation, and on your product support website.

Great Technical Writing (2008). Articles>Documentation>Technical Writing>User Centered Design

Does Design Matter in Comparison to Content?

Few people have ever commented about my blog’s design at all. The same goes with the music intros for my podcasts. I can change the music each time, and no one ever responds. In contrast, if a post has good content, I see a steady stream of comments. My experience leads me to conclude that content is about 90% important, and design is 10% important.

Johnson, Tom H. I'd Rather Be Writing (2008). Articles>Document Design>Visual Rhetoric>Writing

How to Format Your Technical Documents Consistently With a Template

Consistency of a technical documentation is what creates that subliminal sense of trust and confidence in the end-users. Someone once quipped: “it ain’t technical documentation if it ain’t boring.” This of course is not true since I always found technical documents very interesting indeed. I’m the sort of geekish person who can marvel at a well-designed user’s manual for hours and appreciate its beauty and all the effort and thinking that went into its production. I imagine how happy people would be when they use that manual and solve their problems and that, believe it or not, makes me happy as well. That’s the main reason why I’m in this business.

Akinci, Ugur. Technical Communication Center (2009). Articles>Document Design>Style Sheets>Technical Writing

Wurman’s LATCH Model of Information Organization For Technical Documentation

Technical writing has its mechanical aspects that need to be mastered. A good technical writer must know how to use English effectively as well as various software products to produce acceptable technical documents. But I wish technical writing were all about that. The hardest part comes before one even sits down in front of a computer to type the first word. The hardest part in documenting anything is organizing the information in a way that makes sense from the user’s point of view. Otherwise a technical document suddenly looks irrelevant.

Akinci, Ugur. Technical Communication Center (2009). Articles>Information Design>Documentation>Technical Writing

How to Structure FrameMaker Paragraphs While Using the Unstructured Interface

Using the structured features requires advanced training and you probably won’t need them anyways unless you’re doing any “single sourcing” (which is the topic of yet another article). For example if you were doing any XML-based authoring or “database publishing” then you would definitely need to learn how to use the FrameMaker’s structured interface. However, there is an easy way to imitate structured documentation while you are still in the unstructured mode. This is one case in which you can have your cake (unstructured FM) and take a bite out of it too (by enjoying one selected feature of structured documentation).

Akinci, Ugur. Technical Communication Center (2009). Articles>Document Design>Technical Writing>Adobe FrameMaker

Seven Time-Tested Principles to Design a Cover For a Technical Document

Here are seven time-tested design recommendations culled from my 20 years of experience as a professional writer, page layout and information designer.

Akinci, Ugur. Technical Communication Center (2008). Articles>Document Design>Technical Writing

The Case for Simple Numbering

Rather than spend hours coming up with a complex numbering scheme, this might be an excuse to implement something far more straightforward discovered by an extensive readability study at IBM, of which I was a part. My work involved sitting behind a one-way mirror with a stopwatch, watching people take tests that involved, among other things, "how fast can you find Figure 3-4?" We had cameras mounted over the participant's shoulders and could watch them thumb through the documents, and we also monitored eye movements. Then we followed up with a short interview where we got feedback.

Techknowledgecorp (2007). Articles>Document Design>Information Design>Technical Writing

User Paradox with Not Reading User Manuals

Users would save time by reading the manual, but instead they try to figure the application out themselves and then get lost/frustrated as they end up spending even more time getting up to speed with the application.

Johnson, Tom H. I'd Rather Be Writing (2007). Articles>Documentation>User Centered Design>Technical Writing

What Technical Communicators Can Learn from Comics    

Citing the rise of graphic novels, comics, and in particular, Google’s new web browser Chrome, which has a comic-book-style manual, Opsteegh argues that technical communicators can learn a thing or two about conveying information from graphic novelists.

Opsteegh, Michael. Intercom (2009). Articles>Information Design>Technical Writing>Documentation

Creating Topics: Where do you Draw the Line?

It's hard to look at a page of text and try to decide where to divide things to create individual topics. That "bottom up" approach is kind of pointless, in fact. There are better ways.

Armstrong, Eric. Sun Microsystems (2008). Articles>Documentation>Information Design>Technical Writing

Form and Function

A musing on the need to balance documenation that looks good with documentation that has substance.

Nesbitt, Scott. DMN Communications (2009). Articles>Documentation>Document Design>Technical Writing

Duct Tape Technical Writers

In reality, the user just wants a brief, clear explanation of a concept or task. The user will glance and skim — reading behaviors hardly worthy of the elitist grammarian who argues the finer points of “which” versus “that” in restrictive clauses.

Johnson, Tom H. I'd Rather Be Writing (2009). Articles>Document Design>Technical Writing>Minimalism