Technical writing: Difference between revisions

Content deleted Content added

Inline

Revision as of 15:36, 6 June 2008

Technical writing, a form of technical communication, is used in fields as diverse as computer hardware and software, chemistry, the aerospace industry, robotics, finance, consumer electronics, and biotechnology. Technical writing demystifies technical jargon.

Technical writers often work under titles that include phrases like Information Development, Technical Documentation, or Technical Publications. For example, in some organizations, Technical Writers may be called Information Developers, Documentation Specialist, Documentation Engineer, or Technical Content Developers. Technical writers explain complex ideas to technical and nontechnical audiences. This could mean telling a programmer how to use a software library, or telling a consumer how to operate a television remote.

Technical writers gather information from existing documentation, and from subject matter experts. A subject matter expert (SME) is any expert on the topic the writer is working on. Technical writers usually are not SMEs themselves—unless they're writing about creating good technical documentation.

Workers at many levels, and in many different fields, have a role in producing and distributing technical communications. A good technical writer needs strong language skills, and must understand the highly evolved conventions of modern technical communications. For technical documents to be useful, readers must understand and act on them without having to decode wordy and ambiguous prose.

A sample case history

Consider a technical writer writing a cake recipe:

Audience: Is the audience people in home kitchens, or highly trained chefs in professional kitchens?
Source: Is there existing documentation—a rough draft? Who is the subject matter expert (SME)?
Deliverable: Is the deliverable simple text for inclusion in a book, or formatted to final form. Is the target paper, a Web page, or something else?

The technical writer determines that the recipe is written down on the back of a napkin, but is partially indecipherable, so he also must interview an SME—the chef who created it. The audience turns out to be people in their own kitchens, so the writer must adjust the style accordingly, and replace or explain words in the source material like "beurre mixer" or "springform pan." The chef reviews a draft of the recipe (a technical edit), and marks in needed corrections (molasses, not mole asses). The writer prepares a final draft. The chef and any other stakeholders review and approve the recipe and it's off to the printer or website.

History

The origins of technical writing have been variously attributed to Ancient Greece, the Renaissance, and the mid 19th century. However, a clear trend towards the discipline can be seen from the First World War on, growing out of the need for technology-based documentation in the military, manufacturing, electronic and aerospace industries. In 1953, two organizations concerned with improving the practice of technical communication were founded on the East Coast: the Society of Technical Writers, and the Association of Technical Writers and Editors. These organizations merged in 1957 to form the Society of Technical Writers and Editors, a predecessor of the current Society for Technical Communication (STC).

Communicating with the audience

Technical writing is communication to convey a particular piece of information to a particular audience for a particular purpose. It is often exposition about scientific subjects and technical subjects associated with sciences.

Technical writing translates complex technical concepts into simple language to enable a specific user or set of users to perform a specific task in a specific way. (Thus, audience analysis is a key feature of all technical writing.) Quality technical writing usually requires someone specifically trained as a technical writer. Effective communication requires the skills to produce quality content, language, format, and more. To present appropriate content, writers must understand the audience and purpose.

Definitions

Typical technical writing positions require people who can write effective end-user manuals, system design documents, Web sites, and other documents for engineering and IT firms. However, the need for technical writing is broader. A good technical writer can create informational media about a complicated technical subject or task in ways that almost anyone can clearly understand.

Technical writing is a specialized, structured way of writing. It presents information in a manner that best suits cognitive and psychological needs of the readers, so they can respond as the author intended, and achieve the purpose related to the document. The purpose is primarily education. (If secondarily also persuasion, technical writing sometimes overlaps with advertising or marketing). Technical writing is writing formatted and shaped to make reading and understanding as simple, poignant, unequivocal, and enjoyable as possible (i.e., "user friendly"). The competent technical writer continuously asks: "What does the audience know, and what do they need to know, and in what order do they need to know it?"

Precision in technical writing is critical. If something is described incorrectly, readers may act improperly, causing mistakes or even raising issues of liability.

The Society for Technical Communication is the largest technical writing association in the USA. The STC defines technical communication as "The process of gathering information from experts and presenting it to an audience in a clear, easily understandable form." They add: "Technical writing and editing is an umbrella term for any sort of professional communication. It's the interface between your ideas and the rest of the world". The equivalent organisation in the UK is the Institute of Scientific and Technical Communicators (ISTC).

Technical communicators play a vital role in bridging the gap between those who create new ideas or who are subject matter experts (such as scientists and engineers) and those who must understand how to implement their ideas.

Other definitions:

Technical writing is presentation of information that helps its reader solve a particular problem. Technical communicators write, design, and/or edit proposals, manuals, web pages, lab reports, newsletters and many other kinds of professional and technical documents.

The transfer of specialized information from subject matter experts to those who need to use it.

Career growth

The career ladder that a Technical Writer is faced with typically has few levels. A technical writer could grow into a Senior Technical Writer handling more complex projects or a small team. The next step up could be a Documentation Manager handling multiple projects and teams. A few Technical Writers gain expertise in a specific technical domain and branch out into related fields like Software Quality or Business Analysis.

Deliverables

Technical writing is most often associated with online Help and user manuals; however, there are other forms of technical content created by technical writers, including:

Alarm clearing procedures
Annunciator response procedures
Application programming interface programmers' guides
Assembly instructions
Business Guides
Contracts
Certification and accreditation activities
Corporate Annual Reports
Corporate disclaimers
Developer Guides
Feature Design documentation
Getting Started cards or guides
Maintenance and repair procedures
Industrial film or video scripts
Installation guides
Magazine articles
Network administrators' guides
Network configuration guides
Network recovery guides
Policies and procedures
Presentations
Proposals
Reference documents
Release notes
Reports
Requirements documentation
Scientific reports
Site preparation guides
Specifications
Technical papers
Training materials
Troubleshooting guides
Tutorials (multimedia)
User guides
White papers

Journals

IEEE Transactions on Professional Communication

Associations

IEEE Professional Communication Society
Institute of Scientific and Technical Communicators (UK-based)
International Council for Technical Communication
Society for Technical Communication
Technical Communicator's Association of New Zealand (NZ-based)
Usability Professional's Association of New Zealand (NZ-based)
Tekom (pages available in English) Professional organization for technical communication, Germany
Elephant (pages available in English) Professional organization for Technical Writers, Israel

External links

Technical Communication

Technical writing

@@ Line 14: / Line 14: @@
 * '''Deliverable:''' Is the deliverable simple text for inclusion in a book, or formatted to final form. Is the target paper, a Web page, or something else?
-The technical writer determines that he likes sex all night on the back of a napkin, but is partially indecipherable, so he also must interview an SME&mdash;the chef who created it. The audience turns out to be people in their own kitchens, so the writer must adjust the style accordingly, and replace or explain words in the source material like "beurre mixer" or "springform pan." The chef reviews a draft of the recipe (a ''technical edit''), and marks in needed corrections (''molasses'', not ''mole asses''). The writer prepares a final draft. The chef and any other stakeholders review and approve the recipe and it's off to the printer or website.
+The technical writer determines that the recipe is written down on the back of a napkin, but is partially indecipherable, so he also must interview an SME&mdash;the chef who created it. The audience turns out to be people in their own kitchens, so the writer must adjust the style accordingly, and replace or explain words in the source material like "beurre mixer" or "springform pan." The chef reviews a draft of the recipe (a ''technical edit''), and marks in needed corrections (''molasses'', not ''mole asses''). The writer prepares a final draft. The chef and any other stakeholders review and approve the recipe and it's off to the printer or website.
 == History ==