A Brief Note On Technical Writing
Topic: Technical Writing
User Documentation |
There is no debate over the fact that easily accessible, thorough and comprehensible system documentation makes life easier for the end-user, while relieving pressure on technical support staff (and the corporate support budget.) |
Why Use a Technical Writer? |
"Writing" is something that anyone who can form letters and rudimentary sentences can do. However, communicating thoroughly and effectively to a given audience is another matter entirely. It is a common misconception that developers and engineers should be utilized for end-user documentation because "they know the system so well." Although rare exceptions do exist, this is normally a bad idea for a number of reasons: Developers and engineers know the system too well. Consequently it does not occur to them to explain details, which they may take for granted, that may be completely new to the end-user or even to the technician. The expression "this reads like stereo instructions" originates from this type of situation. The level of in-depth familiarity and understanding of the system will also tend to adversely affect their descriptions, often lending a proclivity to include programmatic process information or references that are completely confusing and irrelevant to the end-user. Developers and engineers are highly technical people, normally with extensive training and/or experience. This provides them a large vocabulary of technical jargon that makes communicating with each other very simple, while presenting a string of incomprehensible gibberish to the layperson.
When tightening the corporate belt, executives often consider it cost effective to have system developers create the end-user documentation for the systems they are creating. This enables them to pay fewer employees. However, documentation development time does not significantly change. The result is that the (usually) higher paid developers must invest this time to perform a function that they are normally untrained and unsuited for, to produce documentation that is most commonly far inferior to that which would be produced by a technical writer. |
Enter the Technical Writer: |
A technical writer is a comprehension specialist; a translator between the developer and the end user. To be effective, a technical writer must be proficient in both technical and non-technical terminology. A technical writer must be tech savvy enough to dive into a system he has never seen before and come out the other side with a complete manual. The technical writer maps the ins and outs of the system from the user perspective, the technician perspective, or the management perspective, depending on the type of document being created, and creates a clear, concise and relevant document for the intended audience. |
What About Combining Technical Writing and Programming Positions? |
This is not usually a good idea. If the potential employee has good programming skills, he would not be seeking work at the lower rates of a technical writer. The result is that you get someone that CAN program, but probably not as well (or as mistake free) as you would wish. The better the programmer, the more you will encounter the problems listed above. The best solution is: Do not try to cut corners, put the right person on the right job the first time. - Adam K. Watts |
Posted by adam-k-watts
at 10:56 AM PST
Updated: Tuesday, 3 November 2009 11:39 AM PST