Technical writing

Technical Writing, One part of Technical Communications

Technical writing comprises the largest segment of technical communications.  Technical writers work together with editors, graphic designers and illustrators, document specialists, content managers, instructional designers, trainers, and analysts to produce a wide range of information products for use by internal or external audiences, including:

Contracts	Online and embedded help	Requirements specifications
Customer Service scripts	Policy documents	Simulations
Demonstrations	Process flows	Training courses
Design documents	Project documents	User manuals
FAQs (Frequently Asked Questions)	Product catalogs	Warning labels
How-to videos	Product packaging	Web-based Training
Instructions	Proposals	Websites
Knowledge base articles	Release notes	White papers
	Reference guides

Technical communication jobs include the following:
· Technical writer
· Technical editor
· Technical illustrator
· Information architect
· Usability expert
· User interface designer
· User experience designer
· Technical trainer
· Technical translator
· API writer

Technical documents

Technical writing covers many genres and writing styles depending on the information and audience.  Below are some examples of the most commonly produced technical documents.

1. Instructions and procedures are documents that help either developers or end users operate or configure a device or program.

Examples of instructional documents include user manuals and troubleshooting guides for computer programs, household products, medical equipment, and automobiles.

2. Proposals. Most projects begin with a proposal—a document that describes the purpose of a project, the tasks that will be performed in the project, the methods used to complete the project, and finally the cost of the project.

For example, a technical writer may author a proposal that outlines how much it will cost to install a new computer system, and a teacher may write a proposal that outlines how a new biology class will be structured.

3. Emails, letters, and memoranda are some of the most frequently written documents in a business. Letters and emails can be constructed with a variety of goals—some are aimed at simply communicating information while others are designed to persuade the recipient to accomplish a certain task. While letters are usually written to people outside of a company, memoranda (memos) are documents written to other employees within the business.
4. Press releases. When a company wants to publicly reveal a new product or service, they will have a technical writer author of a press release, a document that describes the product’s functions and value to the public.
5. Specifications are design outlines that describe the structure, parts, packaging, and delivery of an object or process in enough detail that another party can reconstruct it.

For example, a technical writer might diagram and write the specifications for a smartphone or bicycle so that a manufacturer can produce the object.

6. Descriptions are shorter explanations of procedures and processes that help readers understand how something works.

For example, a technical writer might author a document that shows the effects of greenhouse gases or demonstrates how the braking system on a bike functions.

7. Résumés and job applications are another example of technical documents. They are documents that are used in a professional setting to inform readers of the author’s credentials.
8. Technical reports are written to provide readers with information, instructions, and analysis on tasks. Reports come in many forms.

For example, (1) a technical writer might evaluate a building that is for sale and produce a trip report that highlights his or her findings and whether or not he or she believes the building should be purchased. (2) Another writer who works for a non-profit company may publish an evaluation report that shows the findings of the company’s research into air pollution.

9. White papers are documents that are written for experts in a field and typically describe a solution to a technological or business challenge or problem.

Examples of white papers include a piece that details how to make a business stand out in the market or a piece explaining how to prevent cyber-attacks on businesses.

10. Web sites. The advent of hypertext has changed the way documents are read, organized, and accessed. Technical writers of today are often responsible for authoring pages on websites like “About Us” pages or product pages and are expected to be proficient in web development tools

The technical writing process can be divided into five steps:

1. Determine purpose and audience
2. Collect information
3. Organize and outline information
4. Write the first draft
5. Revise and edit

Determining purpose and audience

All technical communication serves a particular purpose—typically to communicate ideas and concepts to an audience, or direct an audience in a particular task. Technical communication professionals use various techniques to understand the audience and, when possible, test content on the target audience.

For example, if bank workers don't properly post deposits, a technical communicator would:

• Review existing documentation (or lack thereof)
• Interview bank workers to identify conceptual errors
• Interview subject matter experts to learn the correct procedures
• Author new material that describes the correct procedures
• Test the new material on the bank workers

I-     Similarly, a sales manager who wonders which of two sites is better for a new store might ask a marketing professional to study the sites and write a report with recommendations. The marketing professional hands the report off to a technical communicator (in this case, a technical editor or technical writer), who edits, formats, and sometimes elaborates the document in order to make the marketing professional's expert assessment usable to the sales manager. The process is not one of knowledge transfer, but the accommodation of knowledge across fields of expertise and contexts of use. This is the basic definition of technical communication.

II-    Audience type affects many aspects of communication, from word selection and graphics use to style and organization. Most often, to address a particular audience, a technical communicator must consider what qualities make a text useful (capable of supporting a meaningful task) and useable (capable of being used in service of that task). A non-technical audience might misunderstand or not even read a document that is heavy with jargon—while a technical audience might crave detail critical to their work. Busy audiences often don't have time to read entire documents, so content must be organized for ease of searching.

III-   Technical communication in the government is particular and detailed. Depending on the segment of government (and country), the government component must follow distinct specifications.

Collecting information

Technical communicators must collect all information that each document requires. They may collect information through primary (first-hand) research—or secondary research, using information from existing work by other authors. Technical communicators must acknowledge all sources they use to produce their work. To this end, technical communicators typically distinguish quotations, paraphrases, and summaries when taking notes.

Organizing and outlining information

Before writing the initial draft, the technical communicator organizes ideas in a way that makes the document flow well. Once each idea is organized, the writer organizes the document as a whole—accomplishing this task in various ways:

·         Chronological -  used for documents that involve a linear process, such as a step-by-step guide that describes how to accomplish something

·         Parts of an object - used for documents that describe the parts of an object, such as a graphic showing the parts of a computer (keyboard, monitor, mouse, etc.)

·         Simple to complex (or vice versa) - starts with easy ideas and gradually goes into complex ideas

·         Specific to general (or vice versa)- starts with many ideas, then organizes the ideas into sub-categories

 

Writing the first draft

After the outline is complete, the writer begins the first draft, following the outline's structure. Setting aside blocks of an hour or more, in a place free of distractions, helps the writer maintain a flow. Most writers prefer to wait until the draft is complete before any revising so they don't break their flow. Typically, the writer should start with the easiest section, and write the summary only after the body is drafted.

The ABC (abstract, body, and conclusion) format can be used when writing a first draft of some document types. The ABC format can also apply to individual paragraphs—beginning with a topic sentence that states the paragraph's topic, followed by the topic, and finally, a concluding sentence.

·         The abstract describes the subject, so that the reader knows what the document covers.

·         The body is the majority of the document and covers topics in depth.

·         The conclusion section restates the document's main topics.

 

Revising and editing

Once the initial draft is laid out, editing and revising can be done to fine-tune the draft into a final copy. Four tasks transform the early draft into its final form, suggested by Pfeiffer and Boogard:

 

Adjusting and reorganizing content

In this step, the writer revises the draft to elaborate on topics that need more attention, shorten other sections—and relocate certain paragraphs, sentences, or entire topics.

 

Editing for style

Good style makes writing more interesting, appealing, and readable. In general, the personal writing style of the writer is not evident in technical writing. Modern technical writing style relies on attributes that contribute to clarity:

·         Headings, lists, graphics

·         Generous white space

·         Short sentences

·         Present tense

·         Active voice (though some scientific applications still use the passive voice)

·         Second and third person as required

Technical writing as a discipline usually requires that a technical writer use a style guide. These guides may relate to a specific project, product, company, or brand. They ensure that technical writing reflects formatting, punctuation, and general stylistic standards that the audience expects.

 

Editing for grammar and punctuation

The writer performs a mechanical edit, checking the document for grammar, punctuation, common word confusions, passive voice, overly long sentences, etc.