Geeks With Blogs
Technical Writing by Mark Metcalfe, Publications Professional June 2009 Entries
India
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, English-language-speaking Indians created a market for technical writers, much of the written content contained somewhat stilted language that a good ......

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

Another Project
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 for several weeks, I called my supervisor one day and asked him if I could have another project. He immediately scheduled a meeting between us in a conference ......

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

CORE Values
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 what to do. Getting or providing clarity is a large part of getting things done. When things are unclear, productivity suffers. When things are clear, ......

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

Tech Writers Need to Learn to Say Yes
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 up with an acrostic “SCAN” to communicate a better way to deal with a growing workload and still meet the demands of the business. Say “Yes.” When approached ......

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

How I Got Started in Technical Writing
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 science, I jumped in. I became one of the computer lab assistants, and my professor noticed that I also had a knack for describing how to do things. ......

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

Intelligent Design
"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 figure out how to get to East 23rd Street. That is because the streets are laid out in a logical progression and you can expect that 41st Street precedes ......

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

Communicating, Technically Speaking
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 people can have trouble articulating exactly what they conceive in their minds; that creates a (sometimes significant) change in the message before ......

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

The Qualities of a Good Documentation Manager
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 writing manager has a broader focus on the corporate brand. A manager that merely maintains the status quo, by having the team update operational information, ......

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

List of Information Types
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 is information in a small document (~20 pages) to familiarize someone with the product (in-depth information available elsewhere), or a high-level tool ......

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

Types of Learning
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) will contain concepts related to baking (the textures of certain breads, the right way to use yeast, and so on). When the information professional understands ......

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

Types of Information
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 of the information. In the broadest of terms, information has three main distinctions: disposable, point-of-need reference, and competence training. ......

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

Nobody Reads the Documentation vs. RTFM
"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. However, (even as a documentation professional), I readily confess that I too tinker with software before I resort to reading about its features. There ......

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

Technical Writing Blog
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 science and there were precious few of us then. It seems that anyone who could show writing prowess could get into the technical writing field. ......

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

Copyright © TechnicalWriting | Powered by: GeeksWithBlogs.net