The person responsible for writing hardware and software documentation, online help, technical definitions and technical product descriptions on Web sites. Quite often, the technical writer is given the task of documenting an application at the last minute, allowing very little time for a thorough understanding of all the options, let alone time for others to read and edit the material before it is published.
A Necessary Evil
Although technical writing is a skill that takes years to learn, and while some companies do appreciate it, most do not. Technical writers are often given less attention than other professionals in the field. In many enterprises, technical writing is considered a necessary evil. As a result, almost all of the documentation we read could be better, and much of it is downright indecipherable. It is no wonder that users and even technical people avoid reading manuals at all costs (see RTFM).
A Note from the Author
Describing technical material is as difficult a job as some of the most complex programming. I know because I have done both for nearly 50 years. However, poor programming is invisible. As long as the program seems to work, you have no idea how many resources are being wasted behind the scenes or how buggy it really is. In fact, people are so used to the computer locking up (crashing), they take it in stride. You also can't know that the application will take five times longer than it should to make a change because it is not well designed.
But, poor writing is visible. It's up front, staring you in the face. And, everyone is an expert in judging its quality. You either comprehend it or you don't. If you have to reread a paragraph over and over, it is poorly written. If written well, the most complicated material can be brought down to bite-sized chunks that are understandable.
A Necessary Evil
Although technical writing is a skill that takes years to learn, and while some companies do appreciate it, most do not. Technical writers are often given less attention than other professionals in the field. In many enterprises, technical writing is considered a necessary evil. As a result, almost all of the documentation we read could be better, and much of it is downright indecipherable. It is no wonder that users and even technical people avoid reading manuals at all costs (see RTFM).
A Note from the Author
Describing technical material is as difficult a job as some of the most complex programming. I know because I have done both for nearly 50 years. However, poor programming is invisible. As long as the program seems to work, you have no idea how many resources are being wasted behind the scenes or how buggy it really is. In fact, people are so used to the computer locking up (crashing), they take it in stride. You also can't know that the application will take five times longer than it should to make a change because it is not well designed.
But, poor writing is visible. It's up front, staring you in the face. And, everyone is an expert in judging its quality. You either comprehend it or you don't. If you have to reread a paragraph over and over, it is poorly written. If written well, the most complicated material can be brought down to bite-sized chunks that are understandable.
 | Reproduced with permission from Computer Desktop Encyclopedia. Copyright (c) 1981-2008 The Computer Language Company Inc. All rights reserved. |
Additional Resources
- Inside India's CAPTCHA solving economy
- No CAPTCHA can survive a human that's receiving financial incentives for solving it, and with an army of low-waged human CAPTCHA solvers officially in the business of "data processing" while earning a mere $2 for solving a thousand CAPTCHA's, I'm already starting to see evidence of consolidation between India's major...
- Blog posts 2008-08-29
- Question about Gov. Sarah Palin
- Is it just me or can anyone get into the official web site of Alaska Gov. Sarah Palin? Have been trying for the past hour to get in. No word yet from the Governor's Office in Anchorage on the site's ability to handle a sudden surge...
- Blog posts 2008-08-29
- IBM claims 'Quicksilver' flash sets data-speed record
- A project under development from IBM is setting new records for data-transfer speeds using solid-state technology with one million input/outputs per second. IBM has said its 'Project Quicksilver' is setting new records for data-transfer speeds on solid-state technology, with its tests showing a disk-storage solution hitting one million input/outputs...
- News items 2008-08-29
- Codename of the day: Nitrogen
- Codename of the day: NitrogenCodeword - "Infection"Can't think why ZDnet aren't trumpeting Microsoft's latest embarassing achievement -Wonder if the US army's robots will be running 'Hasta La Vista'?http://news.bbc.co.uk/1/hi/technology/7583805.stmNasa has confirmed that laptops carried to the ISS in July were infected with a Windows virus known as Gammima.AG.The worm was...
- Discussion threads 2008-08-28
- Jet Screenshot (exe)
- Jet Screenshot is a freeware utility enabling you to share screen snaps via the net in seconds. It allows you to take a snap, edit it and send it to the Web, so that you can immediately provide anyone with a link to the image. Such an approach allows you...
- Software downloads 2008-08-28
- MediaMax / The Linkup: When the cloud fails
- MediaMax / The Linkup: When the cloud failsMore to blameShame on the customers who selected this vendor. When evaluating vendors in the cloud, your RFP should identify exactly how these companies secure, backup, and process your data. I fear that poorly run IT shops like this one will...
- Discussion threads 2008-08-27
- Apple iPhone ad banned
- The Advertising Standards Authority has banned an ad for the iPhone which promised users access to "all parts of the Internet" on their Apple device. The Advertising Standards Authority ASA has banned an ad for the iPhone which promised users access to "all parts of the Internet" on their...
- News items 2008-08-27
- Does Psystar have a legit argument in Apple countersuit?
- Does Psystar have a legit argument in Apple countersuit?AppleIf Apple wants to grow they need to open up their OS. After using Apple computer for few weeks I realize why people choose Windows over Apple inspite of the issues like system-hang, slower wakeup/sleep, etc. Opening up would resolve such issues...
- Discussion threads 2008-08-26
- Does Psystar have a legit argument in Apple countersuit?
- Somewhere in the news coverage of Psystar's countersuit against Apple today, I was reminded of the car analogy I use to help friends and family understand how to buy a computer. Under the hood of a car, everything is the same. There's an engine, transmission, battery and...
- Blog posts 2008-08-26
- How the world watched the Olympics online
- Much has been made of NBC's Olympic numbers, which had the rights for online video in the US, and what that means for Silverlight. I thought the app was solid, the video quality was good, and all in all it was a win for Microsoft and RIAs. In that vein,...
- Blog posts 2008-08-26
- Linux under attack: Compromised SSH keys lead to rootkit
- Linux under attack: Compromised SSH keys lead to rootkitLinux under attack: Compromised SSH keys lead to rootkitLOL! And the hits to linux just keep coming! So thats 4 different incidents within a week's time of how badly linux sucks. Poor linus must be hiding under his bed trying...
- Discussion threads 2008-08-26
- Psystar sues Apple! Claims violation of Sherman Antitrust Act and the Clayton Antitrust Act
- Psystar sues Apple! Claims violation of Sherman Antitrust Act and the Clayton Antitrust ActNice!If only Apple didn't ditch a perfectly viable platform in favor of off-the-shelf hardware for their operating system, half of which came from open source freeware, they might actually have an actual claim. Up to 4...
- Discussion threads 2008-08-26
- Failed government IT: 'The mother of all databases'
- Failed government IT: 'The mother of all databases'Just another reason to keep government smallThis is just another example of how incompitant our government can be. This is a huge problem all over the government and it is wasting billions of our hard earned money while some would like to...
- Discussion threads 2008-08-26
- Failed government IT: 'The mother of all databases'
- The "IT system used to identify terrorist threats that has been crippled by technical flaws," according to a memo from the House of Representatives. The failed system is part of a central US government repository of data called the mother of all databases. by Michael Krigsman
- Blog posts 2008-08-26
- Microsoft, eat your own dog food
- Microsoft, eat your own dog foodReally?"Using hidden aspects of Windows to advantage Microsoft's own applications has been disallowed and behavioral remedies including disclosure demanded."I can't find these in the DOJ settlement, please help: http://www.usdoj.gov/atr/cases/f9400/9495.htmWe can of course look to the EU which did demand documentation of a small subset of...
- Discussion threads 2008-08-26
- Large Hadron Collider aces pre-launch testing
- In a tunnel under the Franco-Swiss border, the world's most powerful particle accelerator passed its final test run before its full-fledged attempt on September 10. Pre-initiation testing of the Large Hadron Collider has now been completed, ahead of the particle accelerator's official launch on September 10. ...
- News items 2008-08-26
- An argument about switching costs
- An argument about switching costsJust a question...If you're going to be using Windows desktop apps with Sun Ray's, doesn't that mean you'll have to deploy Windows Terminal Server too?Why not drop the cost of Sun Ray and just use WTS (if you're paying for it anyway)?RiskThe core of Dr. Dogs...
- Discussion threads 2008-08-26
- X-Box (and Cell Phone) Nation: Election Rests In Digital Hands
- The Democratic convention gets started tonight and in the constant quest for the unconventional technological means of getting out the youth vote, the X-Box is today's "in" device. By itself, this may not be a big deal. There are about 12 million X-Box members around...
- Blog posts 2008-08-25
- Google brings election mobile as reporters become irrelevant
- Worried you'll miss it the second John McCain announces his veep choice? After all, the GOP isn't offering a text-message alert the way Obama did. (Not that that worked so well.) Well, maybe young mothers won't be checking it at 2:38 a.m., but...
- Blog posts 2008-08-25
- Joe Biden loves RIAA, DRM; hates encryption, George Bush
- Joe Biden loves RIAA, DRM; hates encryption, George BushAre You Ready????To have your privacy taken away? For some joker to place more power with the RIAA and MPAA than your own persons.Anyone to push corporate initiatives to be funded by the tax payers should not be in office. ...
- Discussion threads 2008-08-25
Neighboring Terms
Premier Vendor Content Whitepapers, webcasts & resources from our Power Center Sponsors
- Which solar technology will survive?
-
At the Cleantech Forum in San Francisco, Todd Glass of Heller Ehrman moderates a discussion, among tech execs, on the various solar technologies making a difference in the green movement.
- Watch the video >>
- Demo: Virtualization with the Intel® Xeon® Processor
-
In this Flash demo, you'll learn about virtualization performance and features ideal for consolidation, load balancing, and disaster recovery with leading enterprise reliability.
- Watch how the Intel Xeon processor can increase performance and reliability of your servers >>
- Visit the all new ZDNet Enterprise Mobility Hub sponsored by Verizon Wireless. It has the latest news, commentary, and resources for your mobile strategy development.
- Read the latest from Matthew Miller's The Mobile Gadgeteer Blog
- Five steps to protect mobile devices anywhere, anytime
- Watch a video about Distributed Antenna Systems (DAS)
- Learn how you can fetch your email from anywhere
- All this and more on the ZDNet Enterprise Mobility Hub
