Technical Writing

20 Posts | 7 Comments

My goals are to: * Make information useful and easy to find using state-of-the-art information technology. * Apply customer-focused expertise to influence user interface design and user documentation. * Sharply focus a writing group on business objectives.

Technical Writing by Mark Metcalfe, Publications Professional

Feb 13

Topics on Steroids

Comments | Share

Ektron product documentation puts a new twist on topic-based information, creating a streamlined, single-sourced, multi-formatted, topic-based information delivery system.Traditional topic-based documentation links discrete chunks in a chain of related-but-often-isolated, granular bits. Ektron groups the discrete relations into parent topics. The output ......

Posted On Thursday, February 21, 2013 9:58 AM topic-based , help , mobile

Feb 13

Accurate and Complete are not Enough

Comments | Share

Suppose that you asked me to help you write a blog. How would you feel if I handed you the unabridged Oxford English Dictionary and told you that "it has every word you will ever need for your blog. It is the most accurate and complete tome you can find!" While technically true (being accurate and complete), the dictionary is not useful for telling ......

Posted On Friday, February 15, 2013 4:20 PM

Nov 12

Companies and Ships

Comments | Share

I have worked for small, medium, large, and extra large companies and they have something in common with ships. These metaphors have been used before, I know, but I will have a go at them.The small company is like a speed boat, exciting and fast, and can turn on a dime, literally. Captain and crew share a lot of the work. A speed boat has a short range ......

Posted On Thursday, November 15, 2012 11:06 AM

Sep 10

My Writing Methodology

Comments (1) | Share

I was asked about the method I use for documenting products, so I thought I'd blog about it. Topic-based information is essential to today's computer user, whether using web software or shopping online. Most users use information to get "unstuck." Learning methodologies or reading the Great American Novel are for the student or the insomniac. Most experienced ......

Posted On Tuesday, September 14, 2010 4:36 PM

Jul 09

The Evolutionary Role of the Tech Writer

Comments | Share

The one thing that has remained constant for a writer is the role of providing information content. However, providing a context for information is changing, again and again. Technological advances and consumer demands have created an explosion of contexts in which content can be consumed; and they want it all. The high-level contexts for information ......

Posted On Monday, July 27, 2009 3:59 PM

Jul 09

Documentation is YOUR Business

Comments | Share

Your technical writer has completed a 20-page draft of a feature that your team has been working on and sends the team a notice for review, allowing for a week to review it and make comments. You put it on a pile somewhere with a vague intention to skim through it before the next project team meeting. When the meeting arrives, you approve the documentation ......

Posted On Wednesday, July 15, 2009 9:52 AM

Jul 09

Converting Legacy Info to Topics

Comments | Share

Topic-based information is the way to convey information because answers to issues need to be concise, portable, and relevant. The trouble is that many companies have a lot of information already stored in old documentation formats. User guides are becoming rare; and they should, because the effort and cost involved in creating a user guide is too great ......

Posted On Monday, July 6, 2009 9:09 AM

Jun 09

India

Comments | Share

To make a pun about an “elephant in the room,” one cannot discuss technical writing these days without involving India. It is a particularly touchy subject, especially for American writers, but I will hazard a few observations. The quality of writing coming from India in the early days showed that it was in its early stages of development. Although, ......

Posted On Friday, June 26, 2009 1:09 PM

Jun 09

Another Project

Comments | Share

When I left Wang Laboratories and joined Digital Equipment Corporation (DEC to the DECCIES), I was hired to write about how to define tags in the Standard Digital Markup Language (SDML), a proprietary version for developing DEC documentation. My background in programming languages made me a good fit for the job. After I had ramped up on the project ......

Posted On Wednesday, June 24, 2009 2:58 PM

Jun 09

CORE Values

Comments | Share

Some years ago, I developed an acrostic to help guide me as a Technical Publications manager. They have become my CORE values, standing for Clarity, Opportunity, Relevance, and Essentials. These concepts cover many of the issues any worker or manager deals with on a day-to-day basis. Clarity Eighty percent of job anxiety is caused by not being sure ......

Posted On Tuesday, June 23, 2009 10:47 AM

Jun 09

Tech Writers Need to Learn to Say Yes

Comments | Share

As more deliverables were added to the work load of technical writers, I started to hear some of the other writing managers say that we needed to learn how to say “No” to additional work that simply could not be supported by the existing staff. I disagreed, offering what I think is a better approach to the very real problem of understaffing. I came ......

Posted On Monday, June 22, 2009 3:12 PM

Jun 09

How I Got Started in Technical Writing

Comments | Share

It's Saturday, so I feel like writing about how I got started in technical writing. I took a computer class in high school and really liked it. I then took all the computer classes in college that I could. I was a business major at the time, but the computer classes were more appealing to me. When the school created a bachelor's program for computer ......

Posted On Saturday, June 20, 2009 2:33 PM

Jun 09

Intelligent Design

Comments | Share

"Don't go around the block in Boston," my dad advised. He gave me this sage advice long ago because the streets in Boston are not laid out logically. Boston is an old city that grew organically. In fact, many of the winding roads in Massachusetts are paved-over cow paths of old. Think instead of Manhattan. If you are on West 42nd street, you can easily ......

Posted On Friday, June 19, 2009 12:53 PM

Jun 09

Communicating, Technically Speaking

Comments | Share

The goal of an information professional is to communicate ideas to another person that enables that person to apply the ideas to their own goals. Communication is a three-part process, as follows: 1. Form an idea or concept. 2. Transmit the idea. 3. Receive the idea. Despite the fact that forming and transmitting ideas come from a single person, some ......

Posted On Thursday, June 18, 2009 4:46 PM

Jun 09

The Qualities of a Good Documentation Manager

Comments | Share

I was a technical writer for 16 years before managing technical writers. We are a peculiar bunch of folks - kind of like the high school band - talented, but a little quirky. Most of us are introverted and we get our kicks from composing information that people find useful. (I am one of the extroverted ones.) While writers focus on their products, a ......

Posted On Wednesday, June 17, 2009 11:18 AM

Jun 09

List of Information Types

Comments (1) | Share

Thanks for the comments. Here is a more complete listing of information types that is extensive but not exhaustive. Disposable information: Installation information such as wizard text, liner notes in a CD Jacket, and temporary information (passwords). Product Notes to tell the customer what is new in a version of the software. Getting Started, which ......

Posted On Tuesday, June 16, 2009 9:45 AM

Jun 09

Types of Learning

Comments (2) | Share

There are two fundamental reasons why people learn about something: People learn to accomplish a specific task. For example, a recipe for baking a chocolate cake contains specific instructions. People learn to acquire knowledge, which can be applied in more than one way. For example, a reference for baking techniques (perhaps at different altitudes) ......

Posted On Monday, June 15, 2009 11:43 AM

Jun 09

Types of Information

Comments | Share

The information professional must employ several ways to communicate ideas because people have different ways of processing information. The considerations that determine how information should be presented depends on such things as human factors, user experience, and behavioral preferences of the consumer, plus the technical depth, volume, and complexity ......

Posted On Friday, June 12, 2009 12:43 PM

Jun 09

Nobody Reads the Documentation vs. RTFM

Comments | Share

"Nobody reads the documentation," is something I hear a lot. There is another adage in software development that says, "if software is developed properly, then we won't need documentation." This may be true, I do not know, but since I've been in this profession for so long, it may be true that precious few software products were developed properly. ......

Posted On Thursday, June 11, 2009 11:34 AM

Jun 09

Technical Writing Blog

Comments (3) | Share

Hello. My name is Mark Metcalfe and I have been a technical writer and technical writing manager since 1984 when cut and paste meant scissors and tape. A lot has happened in and to the world of technical writing since then. In 1984, most technical writers came from backgrounds like education, biology, English majors. I have a bachelors degree in computer ......

Posted On Wednesday, June 10, 2009 4:42 PM