Science and Technical Writing

A Manual of Style

Philip Rubens

• Publisher: Routledge
• Year: 2002
• ISBN:
  9781135959500
• Edition: 2
• Topic: History
• Subtopic: World History
• Index: History

With this new edition, Science and Technical Writing confirms its position as the definitive style resource for thousands of established and aspiring technical writers. Editor Philip Rubens has fully revised and updated his popular 1992 edition, with full, authoritative coverage of the techniques and technologies that have revolutionized electronic communications over the past eight years.

1.
Audience Analysis and Document Planning

Analyzing an Audience

1.1	Before writing anything, describe an audience by Conducting an audience analysis (1.2), Identifying audience characteristics (1.5), Assessing audience objectives and needs (1.6), Creating an audience profile (1.10).

Conducting an Audience Analysis

1.2	Conduct either a formal or an informal audience analysis. Use formal methods to gather quantifiable data; informal analysis is appropriate for small or poorly funded projects.

1.3	During formal analysis Collect surveys and questionnaire responses, Hold structured interviews, Conduct usability research, such as focus groups, field studies, or usability tests.

Some organizations perform formal analyses as part of their marketing planning.

1.4

During informal analysis, gather information about the audience indirectly by Talking with marketing, development, and other staff who have access to research results and customers; Reading notes and reports by product trainers or maintenance personnel who have had contact with the audience; Reading periodicals that relate to the product, industry, or audience; Talking informally with people who will read the final document.

Identifying Audience Characteristics

1.5

Before you begin writing, identify and consider such important audience characteristics as Educational and professional background, Knowledge and experience levels, English-language ability (see also chapter 2), Reading context (the physical and psychological conditions under which the audience reads the document).

Assessing Audience Objectives and Needs

1.6	Use audience objectives and needs to develop an approach to the document: Objectives reflect the activity the audience wants to be able to perform after reading the document. Needs indicate questions the audience will have that the document should answer.

1.7	Audience objectives may be long-term, short-term, personal, or job-related. They may or may not be directly related to the document.

1.8	Since most readers have job-related objectives for using technical documentation, identify those objectives to determine whether the audience needs the information to perform a task or acquire new knowledge.

1.9

To satisfy the needs of a diverse audience, address both different experience levels and different goals. Follow these general guidelines: Rank goals in terms of the questions the document must answer first, second, third, and so on. Write for one audience group at a time, and indicate which group you are addressing. Remember that other audiences may need the same information. Produce one document for all groups, or divide the information into more than one document. Include navigation aids—tables of contents and lists of figures and tables, page headers and footers, headings within the text, appendixes, tab dividers, and the like—to make information easy to find.

Creating an Audience Profile

1.10

Use the audience characteristics, objectives, and needs to develop a profile: Group related features in a written sketch of the typical reader. For a diverse audience, do a profile for each kind of reader. Form mental images of these composite people. Get to know the profiles before writing anything. Plan the document for typical readers and write to them. Provide the kind of information and presentation readers need to achieve their goals.

Analyzing the Information

1.11

To prepare a document that meets your audience’s needs, analyze the information to be communicated by Identifying information characteristics (1.12), Classifying documents by type (1.17), Using information characteristics to define documents (1.18), Using a typology to guide document development (1.37).

Identifying Information Characteristics

1.12	Documents can be classified into genres, by examining such information characteristics as (see 1.17) Purpose and structure, Assumptions about audience training, Frequency and pattern of use, Textual features.

Purpose and Structure

1.13

Identify a document’s purpose and structure by asking such questions as Does the audience need long-term or short-term knowledge? Is the audience familiar with the task’s or product’s conceptual framework, or should it be presented? A conceptual framework allows readers to generalize from one situation to another. Will the audience need peripheral as well as essential information? How much breadth and depth of information does the audience require? What is the most logical way—chronologically, alphabetically, task-oriented— to organize the document?

Assumptions about Audience Training

1.14	Use the following questions to characterize an audience’s training: Is the audience familiar with the product, service, or software? Is the audience familiar with the task, situation, or problem? Can the document assume the audience has a grasp of basic concepts or background issues?

Frequency and Pattern of Use

1.15	Consider the following questions to identify a document’s frequency and pattern of use: Will the document be referred to often or rarely? Will the document be read linearly or in short, disparate sections?

Textual Features

1.16

Textual features can also be used to classify documents.Will the document have Overview/summary sections? Step-by-step instructions? Narrative explanations? Conceptual models, analogies, and/or examples? Figures, charts, and/or tables? Cross-references and/or navigation aids? Technical terminology, language conventions, and/or symbolic systems?

Classifying Documents by Type

1.17	Although technical documents can be classified in many ways, the following typology offers a useful starting point for developing one within...

Table of contents

• Cover Page
• Title Page
• Copyright Page
• List of Exhibits
• Contributors
• Preface
• 1. Audience Analysis and Document Planning
• 2. Writing for Non-Native Audiences
• 3. Grammar, Usage, and Revising for Publication
• 4. Punctuating Scientific and Technical Prose
• 5. Using Acceptable Spelling
• 6. Incorporating Specialized Terminology
• 7. Using Numbers and Symbols
• 8. Using Quotations, Citations, and References
• 9. Creating Indexes
• 10. Creating Nontextual Information
• 11. Creating Usable Data Displays
• 12. Designing Useful Documents
• 13. Bibliography