Technical writers gather information from existing documentation and from subject matter experts. A subject matter expert (SME) is any expert on the topic that the writer is working on. Technical writers are often not SMEs themselves (unless they are writing about creating good technical documentation). Workers at many levels, and in many different fields, have a role in producing technical communications. A good technical writer needs strong language and teaching skills and must understand the many conventions of modern technical communications.
Technical writing teams or departments are often referred to as Information Development, User Assistance, Technical Documentation, or Technical Publications. Technical writers themselves may be called API Writers, information developers, documentation specialists, documentation engineers, or technical content developers. Advanced technical writers often move into specialized areas such as API writing, information architecture or document management.
Overview
For technical documents to be useful, readers must be able to understand and employ 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 may increase confusion by creating unnecessary technical jargon, or failing to explain unavoidable technical terms that reader would not be expected to be familiar with.
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 notates technical corrections (bake at 350 degrees, not 325 degrees). The writer prepares a final draft 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. Later, the recipe may be translated into multiple languages for different versions of the cookbook.
Types of technical documents
Technical writers use computers and other electronic communications equipment extensively in performing their work. They also work regularly with publishing software and various authoring envirnoments to prepare material directly for the Internet. Technical writers frequently work with word processing, graphic design, page layout, and multimedia software.
The nature of the work is evolving
Increasingly, technical writers are combining text, graphics, images, and sound to create sophisticated deliverables. Technical communication is not required to be dull, and the most effective results are both engaging and memorable.
Three fundamental types of technical documentation
Broadly speaking, technical documentation can be categorized into three types depending on the style of writing, the level of knowledge transferred and the target audience.
- End user assistance. These information products help a user understand how to use a technical software or hardware product. User manuals for computer software, hardware, household products, medical equipment, cell phones, SmartPhones, and other consumer electronics belong in this category.
- Traditional technical documentation. Here the objective of the writer is to communicate with a specific audience. Maintenance guides, appliance/application repair manuals, engineering specifications, research papers, works of reference, annual reports. and articles written for technical journals (to name a few examples) belong in this category.
- Marketing communication. Product catalogs, brochures, advertisements, introductory pages for web sites, press releases, and ad copy belong in this category.
Note: Technical art is also considered a form of technical communication.
Typical deliverables
Technical writing is often associated with online help and user manuals. However, technical writers create many other forms of technical content. These include product release notes, product troubleshooting guides, product user guides, tutorials, software installation guides, API programmers' guides, legal disclaimers, policies and procedures, business proposals, and white papers. Technical writing specifically in support of software applications is commonly referred to as user assistance.
