Technical Writing for Teams: The STREAM Tools Handbook
May 2010, Wiley-IEEE Press
Do you have difficulty producing high-quality documents with multiple contributors when faced with a tight deadline?
Do you need a process that enables global team members to collaborate online as they produce sophisticated documents?
Do you prefer the ease of a WYSIWG desktop publishing tool like Microsoft Word rather than more complex software like LaTeX?
Professors and Graduate Students:
Do you want to streamline the process of writing multi-investigator papers, reports, proposals, and books?
Do you spend a lot of time formatting documents instead of thinking and writing?
Do you write research papers in Microsoft Word and then need to convert them to LaTeX for your thesis?
Do you write research papers in LaTeX and then need to convert them to Microsoft Word when embarking on collaborations with your colleagues from industry?
Do you need to write a research paper and don't know where to start?
Do you need to collaborate with classmates on a long paper and find yourself lost in organizational details rather than immersed in the content?
If you answered "yes" to any of these questions, Technical Writing for Teams: The STREAM Tools Handbook is for you. It provides an easy-to-learn system that streamlines individual and collaborative writing, allowing you and your teams to instantly become more productive and create the highest quality documents in a minimum amount of time. Introduced here are the STREAM Tools—Scientific and Technical wRiting, Editing, And file Management Tools—which unlock your collaborators' potential and addresses team dynamics, separation of duties, and workflow. You'll see how to ensure compatibility among multiple writers, achieve consistent formatting, organize content, integrate bibliographic databases, automate the process of document preparation, and move content between Microsoft Word and LaTeX. Checklists, guidelines, and success stories are also included to help you operate as efficiently as possible.
From planning and editing documents to solving common team writing problems to managing workflow, Technical Writing for Teams: The STREAM Tools Handbook is the one-stop reference that allows teams to collaborate successfully and create unified, effective documents.
CHAPTER 1. INTRODUCTION.
1.1 IN THIS CHAPTER.
1.2 OUR AUDIENCE.
1.2.1 A few horror stories.
1.2.2 Some history.
1.3 THE NEED FOR A GOOD "WRITING SYSTEM".
1.4 INTRODUCING STREAM TOOLS.
1.4.1 What is STREAM Tools?
1.4.2 Why use STREAM Tools?
1.4.3 The software of STREAM Tools.
188.8.131.52 Recommended packages.
184.108.40.206 A brief comparison of Microsoft Word vs. LaTeX: history and myths.
1.5 HOW TO USE THIS BOOK.
CHAPTER 2. QUICK START GUIDE FOR STREAM TOOLS.
2.1 IN THIS CHAPTER.
2.2 A GENERAL OVERVIEW OF THE WRITING PROCESS.
2.3 INTRODUCTION TO WRITING QUALITY TOOLS: THE STREAM TOOLS EDITORIAL MARK-UP TABLE.
2.4 INTRODUCTION TO DOCUMENT DESIGN TOOLS.
2.4.1 Important fundamental concepts.
220.127.116.11 Step 1: Use template files to create your new manuscripts.
18.104.22.168 Step 2: Copy existing elements and paste them into a new location.
22.214.171.124 Step 3: Edit the element.
126.96.36.199 Step 4: Cross-referencing elements.
2.4.2 Creating Elements in a Document.
188.8.131.52 References (literature citations).
2.5 INTRODUCTION TO FILE MANAGEMENT: OPTIMIZING YOUR WORKFLOW.
2.5.1 General principles.
2.5.2 Using a wiki for file management.
2.5.3 Version control.
CHAPTER 3. DOCUMENT DESIGN.
3.1 IN THIS CHAPTER.
3.2 CREATING TEMPLATES.
184.108.40.206 How to create and cross-reference a heading template.
220.127.116.11 How to alter a heading template.
18.104.22.168 Common formatting mistakes in headings.
22.214.171.124 Common stylistic mistakes for headings.
126.96.36.199 Tips and tricks.
188.8.131.52 How to create and cross-reference an equation template.
184.108.40.206 How to alter an equation template.
220.127.116.11 Common formatting mistakes for equations.
18.104.22.168 Common stylistic mistakes for equations.
22.214.171.124 Tips and tricks.
126.96.36.199 How to create and cross-reference a figure template.
188.8.131.52 How to alter a figure template.
184.108.40.206 Common formatting mistakes in figures.
220.127.116.11 Common stylistic mistakes in figures.
18.104.22.168 Tips and tricks for figures.
22.214.171.124 How to create and cross-reference a table template.
126.96.36.199 How to alter a table template.
188.8.131.52 Common typesetting mistakes.
184.108.40.206 Common stylistic mistakes in tables.
220.127.116.11 Tips and tricks for tables.
3.2.5 Front matter.
18.104.22.168 Controlling page numbers.
22.214.171.124 Table of contents.
3.2.6 Back matter.
3.3 USING MULTIPLE TEMPLATES.
3.3.1 Controlling styles.
3.3.2 Switching between single-column and double-column formats.
3.3.3 Master documents.
3.4 PRACTICE PROBLEMS.
3.5 ADDITIONAL RESOURCES.
CHAPTER 4. USING BIBLIOGRAPHIC DATABASES.
4.1 IN THIS CHAPTER.
4.2 WHY USE A BIBLIOGRAPHIC DATABASE?
4.3 CHOICE OF SOFTWARE.
4.4 USING ENDNOTE.
4.4.1 Setting up the interface.
4.4.2 Adding references.
4.4.3 Citing references.
4.5 SHARING A DATABASE.
4.5.1 Numbering the database entries.
4.5.2 Compatibility with BiBTeX.
4.6 FORMATTING REFERENCES.
CHAPTER 5. PLANNING, DRAFTING, AND EDITING DOCUMENTS.
5.1 IN THIS CHAPTER.
5.2 DEFINITION STAGE.
5.2.1 Select your team members.
5.2.2 Hold a kick-off meeting.
5.2.3 Analyze the audience.
5.2.4 Formulate the purpose.
5.2.5 Select the optimum combination of STREAM Tools.
5.3 PREPARATION STAGE.
5.3.1 Evaluate historical documents.
126.96.36.199 Journal articles.
188.8.131.52 Theses and dissertations.
5.3.2 Populate the file repository.
5.3.3 Create a comprehensive outline of the document.
184.108.40.206 Using deductive structures.
220.127.116.11 Using Microsoft Word’s Outline feature.
5.3.4 Populate all sections with "yellow text".
5.3.5 Distribute writing tasks among team members.
18.104.22.168 Choose a drafting strategy.
22.214.171.124 Synchronize writing styles.
5.4 WRITING STAGE.
5.4.1 Enter content.
126.96.36.199 Legacy content.
188.8.131.52 New content.
184.108.40.206 Control versions of shared files.
5.4.2 Request that team members submit their drafts.
5.4.3 Verify that each section is headed in the right direction.
5.4.4 Construct the whole document.
5.4.5 Revise for content and distribute additional writing tasks.
220.127.116.11 Comprehensive editing.
18.104.22.168 STREAM Tools Editorial Mark-up table (STEM Table).
22.214.171.124 Strategies for editing electronic copy using Microsoft Word--an overview of Microsoft Word’s commenting, reviewing, and proofing features.
5.4.6 Distribute additional writing tasks.
5.5 COMPLETION STAGE.
5.5.1 Copy edit the document.
5.5.2 Send out for a final review of content and clarity.
5.5.3 Proofread the document.
5.5.4 Submit the document.
5.5.5 Conduct the final process-improvement review session.
5.7 ADDITIONAL RESOURCES.
CHAPTER 6. BUILDING HIGH QUALITY WRITING TEAMS.
6.1 IN THIS CHAPTER.
6.2 UNDERSTANDING THE BENEFITS AND CHALLENGES OF TEAMWORK.
6.2.1 The payoff of teamwork.
6.2.2 Some principle challenges of teamwork.
6.3 IDENTIFYING TEAM GOALS AND ASSIGNING MEMBER ROLES.
6.3.1 Define roles and procedures clearly.
126.96.36.199 Define team roles.
188.8.131.52 Define team procedures.
6.4 MANAGING TEAMWORK AT A DISTANCE.
6.4.1 Building trust in virtual teams.
6.4.2 Demonstrating sensitivity to cultural differences.
6.5 SELECTING COMMUNICATION TOOLS TO SUPPORT TEAMWORK.
184.108.40.206 Creating a wiki.
220.127.116.11 Monitoring edits.
18.104.22.168 Other suggestions for wiki use.
22.214.171.124 Web pages.
126.96.36.199 Alerts and site management.
6.7 ADDITIONAL RESOURCES.
CHAPTER 7. ASSURING QUALITY WRITING.
7.1 IN THIS CHAPTER.
7.2 CHOOSING THE BEST WORDS 278.
7.2.1 Choose strong words.
188.8.131.52 Use strong nouns and verbs.
184.108.40.206 Choose words with the right level of formality.
7.2.2 Avoid weak words.
220.127.116.11 Check for confusing or frequently misused words.
18.104.22.168 Avoid double negatives, and change negatives to affirmatives.
22.214.171.124 Avoid changing verbs to nouns.
126.96.36.199 Delete meaningless words and modifiers.
188.8.131.52 Steer clear of jargon.
184.108.40.206 Avoid sexist or discriminatory language.
7.3 WRITING STRONG SENTENCES.
7.3.1 Write economically.
7.3.2 Include a variety of sentence types.
7.4 AVOIDING WEAK SENTENCE CONSTRUCTION.
220.127.116.11 Comma splices.
18.104.22.168 Fused or run-on sentences.
22.214.171.124 Misplaced, dangling, or two-way modifiers.
126.96.36.199 Faulty parallelism.
7.5 PUNCTUATING FOR CLARITY.
7.5.1 End punctuation.
188.8.131.52 Question marks.
184.108.40.206 Exclamation points.
7.5.6 Dashes and hyphens.
7.6 FINAL CONSIDERATIONS.
7.6.1 Abbreviations and acronyms.
7.6.5 Fractions and percentages.
7.6.6 Units of measure.
7.7 A FINAL NOTE ON GRAMMAR.
7.8 ADDITIONAL RESOURCES.
CHAPTER 8. CONCLUDING REMARKS.
8.1 IN THIS CHAPTER.
8.2 BUSINESS CASE.
8.3 FREQUENTLY ASKED QUESTIONS.
8.4 SUCCESS STORIES.
8.5 ADDITIONAL READING.
8.5.1 Useful books and articles.
8.5.2 Useful weblinks.
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.
- Teaches how to lead a writing team as well as how to participate as a member.
- Provides both a practical subset of the standard editing symbols and a set of "correction codes" to provide team leaders with extra flexibility when reviewing drafts.
- Provides an exclusive set of "T-Magic" templates that help automate the process of document preparation and largely solve the problem of inconsistent formatting.
- Key concepts are illustrated through instructional videos.
- Draws upon MS Word’s reviewing features and outline view to help writing teams create documents that are unified in their overall approach.
- Demonstrates a set of procedures through which members of a team can all contribute literature references to the same bibliographic database without duplicate entries, overwritten files, and similar problems.
- Shows how collaborative environments such as wikis, bulletin boards, and SharePoint can strengthen group processes and solve many team writing problems, including the very dangerous problem of version control.
- Removes the need to use LaTeX for complicated technical documents.
- Incorporates all the features in the forthcoming Word 2007.