Policy writing and procedure writing is challenging because of the mechanics involved. Words must be carefully chosen; nuances must be considered. Understanding the mechanics of writing these documents is critical; however, an often overlooked aspect should be dealt with before the first word is written. How can policy and procedure writing tiptoe around the elephant in the room that everyone is trying to ignore?
Microsoft’s Visual SourceSafe was not created with technical communicators in mind. It was created for engineers writing software source code. But it is successfully used by technical writers in offices around the world to control documentation.
The readability of technical writing, and technical manuals in particular, especially for second language readers, can be noticeably improved by pairing Theme with Given and Rheme with New. This allows for faster processing of text and easier access to the "method of development" of the text. Typical Theme-Rheme patterns are described, and the notion of the "point of a text" is introduced. These concepts are applied to technical writing and the reader is then invited to evaluate the improvements in readability in a small sample of texts.
'It's all in the manual.' How many times have you heard that - or said it in frustration? After all, when you are the person who wrote the manual, you know that all the answers are there. But time and again readers can't find what they need to know, or don't understand the material. Before you blame the reader, look again at how you've presented the material.
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".
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?
To a non-practitioner, the art of technical writing is a nebulous pursuit to be avoided at all costs. The territory is ripe with jargon and Rube Goldberg devices that are not to be trusted. Besides, who in their right mind would want to be a "Technical Writer" (whatever that is)? But to the artisan, technology and language are the subject and medium in which we create our masterworks.
My advice for those wish to become writers: Write! Write! Write! I have always maintained that great writers are born, and professional writers are made. In the born writers there is an unquenchable thirst for writing, a passion for writing. Writing is a mission. Writing is the soul of the person. The professional writer does it for a living. There is a deadline and the writer can churn out the required number of words.
Documents fail for many reasons. One common mistake is to adopt a ‘one size fits all’ approach to your audience. This works only when generic material, usually of a non-technical nature.
One of the tenets of good technical communication is to avoid culturally specific references, especially if your material is to be translated into other languages. But what’s a culturally specific reference? In simple terms, it’s a word or phrase that has meaning for members of a cultural group, but has limited meaning, no meaning, or some other meaning for people outside that group.
If you are reading this article in INDUS, I assume that the majority of you must be technical writers. The peer-review checklist might be firmly etched in your mind. Please make sure this checklist in disabled. If doing so is not possible, just click the X sign at the top-right corner of the screen. Also, if you have no sense of humor, it is mandatory to click the X sign. I make no apologies for the grammatical errors or syntax errors or sentence structure or comma splices or… whew..pant..pant… this ‘or’ is making me breathless. In fact, I am thriving on these errors because my creative skills are running riot. I have expressed my thoughts in an unconventional manner and, believe me, the feeling is exhilarating and invigorating.
If you’ve used Microsoft Word for any length of time, you’ve probably begun using its key automation features, such as macros and automatic text. If you’re as gung ho as I am, you’ve accumulated a significant collection of these shortcuts. You probably even depend on them for getting work done efficiently. You’ve also probably spent some time adding words to the software’s custom dictionaries, and may even have created specialized dictionaries for certain genres that have their own jargon. Wouldn’t it be a shame if you somehow lost all that hard work?
The dynamic nature of wikis can cause a few headaches when you need to baseline documentation that's on a wiki to correspond with the release of your product. This blog post looks at some ways in which you can try baselining wiki content.
Parents spend years trying to teach their children to be polite, and some of us had to learn at school how to properly address an archbishop. Yet, it seems that advice on courteousness and politeness in technical communication is in short supply; most of us learn these skills through what is euphemistically called “on the job training.” With enough bruises on my back to demonstrate the amount and variety of my experience in this area (though not my skill), here are some of the things I’ve learned.
When giving overview information, be concise. Save the details and flowing language for those that want them or have the time, but don't slow down the skimmer. This doesn't mean skip the details, just keep them from people who don't need them.
To bridge the gap between composition and professional communication studies, we should add multiculturalism to the widely accepted international perspective in professional communication instruction, thus transforming the classroom into a contact zone (Pratt). The practical necessity of intercultural communication in a global marketplace necessitates internationalization. The international perspective, accounting for the heterogeneity of the technical communication audience, focuses on audience analysis and leads us to encourage students to learn about the multiple, cultural layers of audience. A multicultural perspective, however, can teach students of professional communication about the complex relationship between language and ideology and the underlying forces that shape and reflect the ways we use language. Multiculturalism's critical component provides insights into the structures and ideologies of domination/subordination and provides students with the linguistic, intellectual, and moral tools for resisting fear and prejudices. Likewise, the international perspective in professional communication can inform issues of audience analysis in composition.
It may surprise you to find that the wikipedia entry for RTFM is a actually longer than the Wikipedia entry for technical communication. The RTFM response captures the disconnect between technical writers and end-users. Presumably, technical writers include the information in the help material that users ask about. Yet users often don’t take the time to consult the manual to find the answer. If only the users weren’t so lazy, the writer thinks, and mumbles RTFM in response to their question. On the flip side, the user thinks, if only the manual/application weren’t so crappy, then I wouldn’t need to ask others for the information I need.
I’ve realized that having a blog helps me think more about my professional activities and interactions than I would otherwise. I give them more thought because I think about whether they’re something I can write about.
The SMEs had a choice between two sets of tables they could use to input key product data. If their part of the project used items from the A list, they were supposed to use table A. If their part of the product used items from the B list, they were supposed to use table B. In almost every case, the SMEs used the wrong table, leaving gaps where their information did not conform to the columns of the tables.