Technical writing

From Wikipedia, the free encyclopedia

Technical writing, a form of technical communication, is a style of formal writing and is used in fields as diverse as computer hardware and software, chemistry, the aerospace industry, robotics, finance, consumer electronics, and biotechnology. 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 control.

Technical writers often labor 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 Specialists, Documentation Engineers, API Writers or Technical Content Developers.

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 are usually 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.

[edit] Illustrative example of technical writing

For technical documents to be useful, readers must understand and act on them without having to decode wordy and ambiguous prose. Good technical writing clarifies technical jargon; that is, it presents useful information that is clear and easy to understand for the intended audience. Poor technical writing, on the other hand, often creates unnecessary technical jargon, and sows seeds of confusion and misunderstanding in the readers' minds.

Consider a technical writer writing a cake recipe:

Audience: Is the audience composed of 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 a 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 must also interview a SME—the chef who created it. He is told that the audience consists of 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 technical corrections (bake at 350 degrees, not 325 degrees). The writer prepares a final draft and the document goes into English edit to ensure that all instructions are grammatically correct. The document owner and any other stakeholders perform a final review and approve the recipe before it is sent to the printer or website.

[edit] 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. To present appropriate content, writers must understand the audience and purpose. Thus, audience analysis is a key feature of all technical writing.

[edit] 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, electronics, 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).

[edit] Career growth

A technical writer has no true career levels, but can move up into management of other writers. A technical writer could grow into a senior technical writer position, handling complex projects or a small team of writers and editors. The next step up could be a documentation manager handling multiple projects and teams. Technical writers might also gain expertise in a specific technical domain and branch out into related forms, like software quality or business analysis, should they have become experts in these fields themselves.

Senior writers in some organizations also are being called as Individual Contributor or API Writers. In API/software documentation, IC's work with a team of developers or testers working across global locations. In such software development or Software Research organizations, an IC plays a very important role in the delivery of API/Software documentation. ICs are also seen in major product development/service based companies working with a wide range of projects.

[edit] 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 API programmers' guides, corporate disclaimers, policies and procedures, business proposals, release notes, troubleshooting guides, user guides and white papers.

[edit] Parodies

Technical writing is often subject to parody by lay-people; to avoid this, a technical writer must consider the target audience with every word chosen.

As a classic (and humorous) example, an early Jim Henson Muppet sketch appears to parody a technical training manual. A prototype of Cookie Monster, with sharper teeth, consumes a complex machine while it reads its own instruction manual aloud. This would be a rather extreme example of the effects of a technical writer not consistently and frequently stating the design goals of the device in question.