Technical Writing for Teams The STREAM Tools Handbook

by Mamishev, Alexander; Williams, Sean

• ISBN13: 9780470229767
• ISBN10: 0470229764
• eBook ISBN(s): 9780470602690
• Edition: 1st
• Format: Paperback
• Copyright: 2010-05-03
• Publisher: Wiley-IEEE Press
• More Book Details

Summary

The book is designed to help authors of technical documents overcome the following common problems:Inconsistent formatting. Inconsistent formatting arises as individual team members incorporate their own material into the emerging document. One especially difficult problem is the numbering of headings, figures, equations, and in-text literature citations and reference lists.Need to follow house style. Many documents need to follow the requirements of a particular journal, funding organization, etc.Incorrect grammar, punctuation, and mechanics and poor writing.Disunity. Document disunity refers to all the problems that arise when multiple people work on a single document.Poorly managed literature citations.The industry-academic tool split. Academic research groups very often work in LaTeX. Industry groups rarely do. Moving content between MS Word and LaTeX is difficult. This difference in tool use has complicated industry-academic collaboration for a long time.

Author Biography

ALEXANDER V. MAMISHEV is an Associate Professor in the Department of Electrical Engineering at the University of Washington, as well as the Director of the Sensors, Energy, and Automation Laboratory and the Director of Industrial Assessment Center.

SEAN D. WILLIAMS is Associate Dean of the Graduate School and Associate Professor of Professional Communication at Clemson University. He is the cofounder of the Carolinas Virtual Worlds Consortium, and conducts research on collaborative writing, virtual teams, and technical communication.

Table of Contents

Preface

Acknowledgments

Introduction

In this Chapter

Our Audience

A few horror stories

Some history

The Need For a Good "Writing System"

Introducing Stream Tools

What is STREAM Tools?

Why use STREAM Tools?

The software of STREAM Tools

Recommended packages

A brief comparison of Microsoft Word vs. LaTeX: history and myths

How to Use this Book

Exercises

Quick Start Guide For Stream Tools

In this Chapter

A General Overview of the Writing Process

Introduction to Writing Quality Tools: The Stream Tools Editorial Mark-Up Table

Introduction to Document Design Tools

Important fundamental concepts

Step 1: Use template files to create your new manuscripts

Step 2: Copy existing elements and paste them into a new location

Step 3: Edit the element

Step 4: Cross-referencing elements

Creating Elements in a Document

Headings

Equations

Figures

Tables

References (literature citations)

Introduction to File Management: Optimizing Your Workflow

General principles

Using a wiki for file management

Version control

Conclusions

Exercises

Document Design

In this Chapter

Creating Templates

Headings

How to create and cross-reference a heading template

How to alter a heading template

Common formatting mistakes in headings

Common stylistic mistakes for headings

Tips and tricks

Equations

How to create and cross-reference an equation template

How to alter an equation template

Common formatting mistakes for equations

Common stylistic mistakes for equations

Tips and tricks

Figures

How to create and cross-reference a figure template

How to alter a figure template

Common formatting mistakes in figures

Common stylistic mistakes in figures

Tips and tricks for figures

Tables

How to create and cross-reference a table template

How to alter a table template

Common typesetting mistakes

Common stylistic mistakes in tables

Tips and tricks for tables

Front matter

Controlling page numbers

Table of contents

Back matter

Appendices

Indices

Using Multiple Templates

Controlling styles

Switching between single-column and double-column formats

Master documents

Practice Problems

Headings

Equations

Figures

Tables

Additional Resources

Exercises

Using Bibliographic Databases

In this Chapter

Why Use a Bibliographic Database?

Choice of Software

Using Endnote

Setting up the interface

Adding references

Citing references

Sharing a Database

Numbering the database entries

Compatibility with BiBTeX

Formatting References

Exercises

Planning, Drafting, and Editing Documents

In this Chapter

Definition Stage

Select your team members

Hold a kick-off meeting

Analyze the audience

Formulate the purpose

Persuasion

Exposition

Instruction

Select the optimum combination of STREAM Tools

Preparation Stage

Evaluate historical documents

Journal articles

Proceedings/papers

Theses and dissertations

Proposals

Reports

Populate the file repository

Create a comprehensive outline of the document

Using deductive structures

Using Microsoft Word's Outline feature

Populate all sections with "yellow text"

Distribute writing tasks among team members

Choose a drafting strategy

Synchronize writing styles

Writing Stage

Enter content

Legacy content

New content

Control versions of shared files

Request that team members submit their drafts

Verify that each section is headed in the right direction

Construct the whole document

Revise for content and distribute additional writing tasks

Comprehensive editing

STREAM Tools Editorial Mark-up table (STEM Table)

Strategies for editing electronic copy using Microsoft Word--an overview of Microsoft Word's commenting, reviewing, and proofing features

Distribute additional writing tasks

Completion Stage

Copy edit the document

Send out for a final review of content and clarity

Proofread the document

Submit the document

Conduct the final process-improvement review session

Exercises

Additional Resources

Building High Quality Writing Teams

In this Chapter

Understanding the Benefits and Challenges of Teamwork

The payoff of teamwork

Some principle challenges of teamwork

Identifying Team Goals and Assigning Member Roles

Define roles and procedures clearly

Define team roles

Define team procedures

Managing Teamwork at a Distance

Building trust in virtual teams

Demonstrating sensitivity to cultural differences

Selecting Communication Tools To Support Teamwork

Wikis

Creating a wiki

Editing

Organizing

Monitoring edits

Other suggestions for wiki use

SharePoint

Lists

Web pages

Alerts and site management

Exercises

Additional Resources

Assuring Quality Writing

In this Chapter

Choosing the Best Words 278

Choose strong words

Use strong nouns and verbs

Choose words with the right level of formality

Avoid weak words

Check for confusing or frequently misused words

Avoid double negatives, and change negatives to affirmatives

Avoid changing verbs to nouns

Delete meaningless words and modifiers

Steer clear of jargon

Avoid sexist or discriminatory language

Writing Strong Sentences

Write economically

Include a variety of sentence types

Avoiding Weak Sentence Construction

Comma splices

Fragments

Fused or run-on sentences

Misplaced, dangling, or two-way modifiers

Faulty parallelism

Punctuating For Clarity

End punctuation

Periods

Question marks

Exclamation points

Commas

Semicolons

Colons

Apostrophes

Dashes and hyphens

Final Considerations

Abbreviations and acronyms

Capitalization

Numbers

Dates

Fractions and percentages

Units of measure

A Final Note on Grammar

Additional Resources

Concluding Remarks

In this Chapter

Business Case

Frequently Asked Questions

Success Stories

Additional Reading

Useful books and articles

Useful weblinks

EXERCISES

Table of Contents provided by Publisher. All Rights Reserved.