parrt three: processes and guidelines in technical writing

PARRT THREE:

Processes and Guidelines in Technical Writing

Writing Process: from Audience to Rough Draft

1. F I N D I N G A T O P I C

2. A N A LY Z I N G A U D I E N C E A N D P U R P O S E

3. N A R R O W I N G D O W N Y O U R T O P I C

4. O U T L I N I N G Y O U R R E P O RT

5. A R R A N G I N G T H E PA RT S O F T H E O U T L I N E

6. W R I T I N G A R O U G H D R A F T A N D C O M PA R I N G I T T O T H E O U T L I N E

7. R E V I S I N G T H E R O U G H D R A F T.

Task Analysis

The job of the technical writer is to create information for products that help users use products. The goal is not simply to describe how the product works.

When you write instructions, procedures, and "guide" or user-guide information, you normally must use a task approach. That means providing steps and explanations for all the major tasks that users may need to perform. There are two approaches for task analysis: functional orientation and task orientation.

1. Writing with a functional orientation:

It explains each function, feature, or interface element of a product.If this approach shows up in user guides. It is meant for nontechnical readers — perhaps because the writers are inexperienced, untrained, or technical.

2. Writing with a task orientation:

1. Identify the tasks users will need to perform with the product.

2. structure your document accordingly. 3. Make your headings and subheadings task

oriented in their phrasing. like "How to adjust the volume, "Adjusting the volume," or "Adjust the volume." It does not mean phrasing like "Volume" or "Volume Adjustment."

This section shows you a step-by-step method for: "translating" technical discussions, that is, specific techniques you can use to make difficult technical discussions easier for nonspecialist readers to understand.

Translating technical information

Definitions of unfamiliar termsComparisons to familiar thingsElaborating the processProviding descriptive detailProviding illustrationsProviding examples and applicationsShorter sentences

Methods for Translating Technical Information

Stronger transitions and overviewsa) Repetition of key wordsb) Transition words and phrases.c) Reviews of topics covered and topics to be

coveredThe "in-other-words" techniquePosing rhetorical questionsExplaining the importance

Providing historical backgroundReviewing theoretical backgroundProviding the human perspectiveCombining the translating techniques

Power Revision Techniques

How you organize your writing, and how you link it all up together. This means:

Looking for potential problems and then fixing those problems

There are: structure-level revisionsSentence-level revisions

structure-level revisions

Checking contentsChecking organizationStrengthening topic sentences Strengthening transitionsChecking paragraph length and contents

Sentence-level revisions

Revising weak be-verbsRevising noun stacksRevising redundant phrasingRevising weak expletivesRevising weak passive-voice sentencesRevising subject-verb mismatchesRevising sentence-length problems

Documentation

Documenting your resources makes your work legal and makes it easier for others to find resources of their interest.

To document your resources, USE: The number system (Scientific documentation)

Cross References

Point readers to other places in the same document or to other information sources where related information can be found.

A cross-reference consists of: Name of the source being referencedPage numberSubject matter of the cross-reference

Types of cross-reference

Internal cross-reference:Refers to some other part of the same

document.

External cross-reference:Refers to information outside of the current

document

Strategies for Peer-Reviewing and Team-Writing

Strategies for Peer-ReviewingInitial meetingPeer-reviewing strategiesPeer-review summary

Strategies for Team-WritingAssembling the teamPlanning the projectScheduling the projectBalancing workloadSetting up a style guide or style sheetReviewing drafts and finishing

Good Luck!