Technical Writing, a form of technical communication, is a style of formal writing and business communication, used in fields as diverse as computer hardware and software, chemistry, the aerospace industry, robotics, finance, consumer electronics, and biotechnology. Good technical writing clarifies technical jargon; that is, it presents useful information that is clear and easy to understand for the intended audience.
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.
One of the problems I’ve had to combat over the years has been boredom/burnout — that feeling you get either when you’ve been on the same project for too long or a you’re on new project that just feels like exactly what you’ve been working on for years. How do you breath life into work that you’ve done many, many times before?
Information development organizations are under increasing pressure to implement single-sourcing or other automated and highly structured document development processes. Forces driving this trend include translation requirements, niche marketing, the convergence of software and documentation, and shrinking cycle times and budgets. Initially, these changes threaten to remove everything that is challenging and interesting about the technical writer’s work. However, technical writers who successfully adapt to this new environment will find more opportunity than ever to use their analysis and writing skills and to develop additional negotiation and process management capabilities.
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.
There has been a tremendous growth in the software industry and some growth in technical writing. Most of my columns ten years ago were rants about the poor state of our manuals and our software. Today, I think the humblest of companies is producing great stuff. The reason for it is simple--globalisation and the Internet.
In today's complex global economy, good technical documentation is essential. We have all been frustrated when it is lacking -- when we can't find what we need in an owner's manual, when on-line help is no help at all, when newsletter articles are confusing, when installation instructions are incomplete, or when we can't find what we need on a web site.
A DVR operating instruction manual. An assembly manual for a coffee table. A how-to guide for using the latest smart phone. What do all of these have in common? They are the results of the hard work of a technical writer. For those who are tech savvy and keep a copy of a MacBook instruction manual handy for their bedside reading, a career as a technical writer may be the right fit. Your job as a technical writer would be to translate difficult-to-understand information into layman's terms (think: operating instructions, how-to manuals, assembly instructions, and online help information). You may work in engineering, scientific, or healthcare fields, simplifying highly specialized information for the average Joe. Also, you'd work with computers and electronic publishing software, including graphic design, page layout, and multimedia software. Some technical writers who are self-employed or work for a technical consulting firm do freelance or contract work.
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.
This collection of thirty-six articles exposes the problem and the promise of historical research in technical writing. The central problem is that historical research in technical writing has too often been focused only on celebrated authors or scientists as technical writers. The central promise contained in some very recent essays is that historical research in technical communications is beginning to consider the slow evolution of technical communication taking place across a broad spectrum of both celebrated and uncelebrated writers. This historical approach, though more difficult to carry out, is immensely more accurate and meaningful.
Estimating the amount of time it takes to write documentation is tricky as it relies on many differing, subtle, factors and, for many people working outside of a highly regimented and heavily project managed team, it tends to boil down to a mixture of guesswork and experience. However, it’s not impossible to come up with a more reasoned estimate as long as you don’t mind doing a little planning.
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.