Technical Writing for Teams: The STREAM Tools Handbook

PREFACE.

ACKNOWLEDGMENTS.

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.

1.4.3.1 Recommended packages.

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

1.5 HOW TO USE THIS BOOK.

1.6 EXERCISES.

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.

2.4.1.1 Step 1: Use template files to create your new manuscripts.

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

2.4.1.3 Step 3: Edit the element.

2.4.1.4 Step 4: Cross-referencing elements.

2.4.2 Creating Elements in a Document.

2.4.2.1 Headings.

2.4.2.2 Equations.

2.4.2.3 Figures.

2.4.2.4 Tables.

2.4.2.5 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.

2.6 CONCLUSIONS.

2.7 EXERCISES.

CHAPTER 3. DOCUMENT DESIGN.

3.1 IN THIS CHAPTER.

3.2 CREATING TEMPLATES.

3.2.1 Headings.

3.2.1.1 How to create and cross-reference a heading template.

3.2.1.2 How to alter a heading template.

3.2.1.3 Common formatting mistakes in headings.

3.2.1.4 Common stylistic mistakes for headings.

3.2.1.5 Tips and tricks.

3.2.2 Equations.

3.2.2.1 How to create and cross-reference an equation template.

3.2.2.2 How to alter an equation template.

3.2.2.3 Common formatting mistakes for equations.

3.2.2.4 Common stylistic mistakes for equations.

3.2.2.5 Tips and tricks.

3.2.3 Figures.

3.2.3.1 How to create and cross-reference a figure template.

3.2.3.2 How to alter a figure template.

3.2.3.3 Common formatting mistakes in figures.

3.2.3.4 Common stylistic mistakes in figures.

3.2.3.5 Tips and tricks for figures.

3.2.4 Tables.

3.2.4.1 How to create and cross-reference a table template.

3.2.4.2 How to alter a table template.

3.2.4.3 Common typesetting mistakes.

3.2.4.4 Common stylistic mistakes in tables.

3.2.4.5 Tips and tricks for tables.

3.2.5 Front matter.

3.2.5.1 Controlling page numbers.

3.2.5.2 Table of contents.

3.2.6 Back matter.

3.2.6.1 Appendices.

3.2.6.2 Indices.

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.4.1 Headings.

3.4.2 Equations.

3.4.3 Figures.

3.4.4 Tables.

3.5 ADDITIONAL RESOURCES.

3.6 EXERCISES.

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.

4.7 EXERCISES.

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.4.1 Persuasion.

5.2.4.2 Exposition.

5.2.4.3 Instruction.

5.2.5 Select the optimum combination of STREAM Tools.

5.3 PREPARATION STAGE.

5.3.1 Evaluate historical documents.

5.3.1.1 Journal articles.

5.3.1.2 Proceedings/papers.

5.3.1.3 Theses and dissertations.

5.3.1.4 Proposals.

5.3.1.5 Reports.

5.3.2 Populate the file repository.

5.3.3 Create a comprehensive outline of the document.

5.3.3.1 Using deductive structures.

5.3.3.2 Using Microsoft Word’s Outline feature.

5.3.4 Populate all sections with "yellow text".

5.3.5 Distribute writing tasks among team members.

5.3.5.1 Choose a drafting strategy.

5.3.5.2 Synchronize writing styles.

5.4 WRITING STAGE.

5.4.1 Enter content.

5.4.1.1 Legacy content.

5.4.1.2 New content.

5.4.1.3 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.

5.4.5.1 Comprehensive editing.

5.4.5.2 STREAM Tools Editorial Mark-up table (STEM Table).

5.4.5.3 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.6 EXERCISES.

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.

6.3.1.1 Define team roles.

6.3.1.2 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.

6.5.1 Wikis.

6.5.1.1 Creating a wiki.

6.5.1.2 Editing.

6.5.1.3 Organizing.

6.5.1.4 Monitoring edits.

6.5.1.5 Other suggestions for wiki use.

6.5.2 SharePoint.

6.5.2.1 Lists.

6.5.2.2 Web pages.

6.5.2.3 Alerts and site management.

6.6 EXERCISES.

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.

7.2.1.1 Use strong nouns and verbs.

7.2.1.2 Choose words with the right level of formality.

7.2.2 Avoid weak words.

7.2.2.1 Check for confusing or frequently misused words.

7.2.2.2 Avoid double negatives, and change negatives to affirmatives.

7.2.2.3 Avoid changing verbs to nouns.

7.2.2.4 Delete meaningless words and modifiers.

7.2.2.5 Steer clear of jargon.

7.2.2.6 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.

7.4.1.1 Comma splices.

7.4.1.2 Fragments.

7.4.1.3 Fused or run-on sentences.

7.4.1.4 Misplaced, dangling, or two-way modifiers.

7.4.1.5 Faulty parallelism.

7.5 PUNCTUATING FOR CLARITY.

7.5.1 End punctuation.

7.5.1.1 Periods.

7.5.1.2 Question marks.

7.5.1.3 Exclamation points.

7.5.2 Commas.

7.5.3 Semicolons.

7.5.4 Colons.

7.5.5 Apostrophes.

7.5.6 Dashes and hyphens.

7.6 FINAL CONSIDERATIONS.

7.6.1 Abbreviations and acronyms.

7.6.2 Capitalization.

7.6.3 Numbers.

7.6.4 Dates.

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.

8.6 EXERCISES.