Geeks With Blogs

Technical Writing by Mark Metcalfe, Publications Professional
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 ......

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 ......

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 ......

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 ......

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 ......

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 ......

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 ......

26
Jun 09
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, ......

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 ......

23
Jun 09
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 ......

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 ......

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 ......

"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 ......

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 ......

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 ......

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 ......

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) ......

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 ......

"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. ......

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 ......

Copyright © TechnicalWriting | Powered by: GeeksWithBlogs.net | Join free