Technical Writing For Dummies

Title Page
Copyright Page
Table of Contents
Introduction
About This Book
Foolish Assumptions
Icons Used in This Book
Beyond the Book
Where to Go from Here
Part 1 What It Takes to Write Technical Docs
Chapter 1 Working as a Technical Writer
Technical Writers Spring from All Walks of Life
Documentation Is Part of Our Everyday Lives
Technical Writing Differs from Business Writing
Documents of the business kind
Documents of the technical kind
Assigning Responsibility for Technical Documents
It’s About Strategy, Not Software
What You Need to Succeed
Seeing Is Believing
Case 1
Before document
After
Case 2
Before document
After document
Case 3
Before document
After document
Beyond the Writing
Create a dynamic portfolio
Create a LinkedIn profile
Present your business card
Tech Writing Career Trajectories
Translate technical documents
Become a UX writer
Soar into the cloud
Become a scrum master
Chapter 2 Putting Together a Team and a Plan
Benefiting from the Team Experience
Know who’s on first
Turn stumbling blocks into stepping stones
Choosing the Right Type of Delivery
Completing a Production Schedule
Make the production schedule a “must”
Timing is everything
The Power of Brainstorming
Generating an Outline
Write a traditional outline
Use a decimal numbering system
Create an annotated table of contents
Getting Your Arms around the Document
Conduct internal research
Conduct external research
Part 2 The Write Stuff
Chapter 3 Completing a Technical Writing Brief
How to Feed a Martian
Will Zeb go hungry?
Fill Zeb’s empty stomach
Getting Jump-Started with the Technical Writing Brief
Slicing and Dicing the Technical Writing Brief
About the document
Learner profile
Key issues
Budget
Project team
Milestones
Approval cycle
Chapter 4 Crafting a Draft
Psyching Yourself Up
Getting Down to Business
Integrating the Editing Process
The wallpaper edit
Hold on to your ego
Revising Your Work
Chapter 5 Designing Documents to Enhance the User Experience
Grabbing Your Learners’ Attention
Using Whitespace
Giving Learners a Break
Limit sentences to 20 syllables
Limit paragraphs to eight lines
Harnessing the Power of Headlines
Understand the business value of headlines
Know the value of SEO in headlines
Putting It on the List
Use bulleted lists
Use numbered lists
Use parallel structure
Parallel bulleted list
Nonparallel bulleted list
Punctuate lists
Avoid laundry lists
Keeping It Short and Simple (KISS)
Presenting the Natural Order of Things
Put the bottom line up front
Put the bottom line at the end
A Picture (Pixel) Is Worth a Thousand Words
Include pie charts
Include line charts
Include bar charts
Histograms
Pareto charts
Gantt charts
Include scatter charts
Include flowcharts
Tabling That Thought
Create a formal table
Create an informal table
Adding More Value to Your Visuals
Scale for size
Location, location, location
What’s your visual preference?
Chapter 6 Honing the Tone
Giving ’Em a Little KISS
KISS your technical documents
Cut to the quick
Accentuating the Positive
Fill the glass half full
Empty the glass
Loving the Active Voice
Bring documents to life with active voice
Use passive voice strategically
Looking Through Lens of Social Justice
Show respect for all
Consider gender-neutral pronouns
Consider a sentence reword
Being Clear and Consistent
Define terms and acronyms
Who’s laughing?
When to be a jargon junkie
Chapter 7 Fine-Tuning toward the Ideal
Crossing Your T’s and Dotting Your I’s
Editing versus proofreading
Test your proofreading skills
Editing for Clarity and Flow
Track changes
Use an editing checklist
Determining the Readability of Your Documents
Don’t save the best for last
Try readability testing
Ramp up your readability
Use online readability assessments
Part 3 Frequently Written Docs
Chapter 8 Writing User Manuals and More
Understanding the Value of a Well-Written Manual
Provide a good customer experience
Avoid legal issues
Know what to include
Know your audience
Getting Up and Running
Determining Style and Format
Taking Each Step, Then Acting on It
The devil is in the details
Check out the contents of the box
Writing for Between the Covers
Prepare a table of contents
Append appendixes
Generate a glossary
Itemize an index
Testing, Testing, 1-2-3
Determining Frequently Asked Questions (FAQs)
Preparing an Instructional Video for Streaming
Start with a script
Choose a video host
Creating a Simulated Learning Experience (SLE)
Apply SLE to simulations
Imagine what’s next: The metaverse
Join-the-Dots Brain Teaser
Chapter 9 Preparing Abstracts
Types of Abstracts
Preparing an Informative Abstract
What to include
What to omit
Using Abstracts Effectively
Chapter 10 Creating Spec Sheets
Knowing What to Include
Following the Natural Order of Things
Phase 1: Requirement specs
Phase 2: Functional specs
Phase 3: Design specs
Phase 4: Test specs
Phase 5: End-user specs
Considering Some Examples
Chapter 11 Generating Questionnaires
Differentiating between Questionnaires and Surveys
Ask unbiased questions
Avoid double-barreled questions
Using Distribution Channels
Designing the Form
Posing the Questions
Include closed-ended questions
Use yes, no, and in between
Give multiple choices
Include a sliding scale
Select open-ended questions
Learning from the Results
Chapter 12 Preparing for Technical Presentations
Getting to Know Your Audience
Getting Ready for Prime Time
Timing is everything
Get comfortable with your environment
Conveying Your Message with Confidence and Competence
Use repetition strategically
Leave these phrases at the door
Organizing for High Impact
Presenting Visuals
Giving Them Something to Remember You By
Give handouts before your presentation
Give handouts after your presentation
Checking Out Before Checking In
Chapter 13 Abridging for Executive Summaries
An Executive Summary Is Critical
Summing It Up
Include graphics
Use an appropriate tone
Learn from a success story
Delving into the Executive Summary for a Business Plan
Part 4 Tech Tools
Chapter 14 Collaborating with Others
Collaboration Is about People
Build trust
Give constructive feedback
Find solutions to challenges
Collaborative Team Etiquette: Etta Kitt Says
Get started
Communicate effectively
Using Collaboration Tools
Allow team members time to train
Consider these prolific providers
Get what you pay for
Know what you need
Perform an accessibility check
An ounce of prevention. . .
Storing Data in the Cloud
Understand governance
Prevent security breaches
Chapter 15 Videoconferencing
Using the Goldilocks Theory for Selecting
Find the best platform for your needs
Identify additional equipment needs
Creating a Culture of Inclusivity
Know the accessibility of an app
Videoconferencing Pros and Woes
Pros
Woes
Are You Ready for Your Close-Up?
Fostering Cohesive Hybrid Teams
Suffering Burnout or Videoconferencing Fatigue?
Recognize the signs
Determine other options
Planning for Success
Onscreen Netiquette: Etta Kitt Says
Dos
Taboos
Chapter 16 Offering eLearning
Understanding the Forms of eLearning
Preparing the Learning Objectives
Delivering eLearning
Use an LMS
Use an SCORM
Use xAPI
Elements of eLearning
Choosing Your Software
Buy it
Construct it
Outsource it
Creating Learning Modules
Chunk information
Check for readability
Meet expectations
Solving Business Problems
Designing a Process
Set your sights
Plan for the learner’s experience
Design the training experience
Make a prototype
Create a storyboard
Testing, Testing, 1-2-3
Fix bugs and glitches
Evaluate training
Chapter 17 Surfing the Net
Avoiding the Internet Sharks
Dodging Other Internet Pitfalls
Decoding Error Messages
Searching for the Holy Grail
Boolean searches
Other syntax searches
Speed surfing
Boosting Search Engine Optimization (SEO)
Understand pay-per-click (PPC)
Go organic (non-paid results)
Avoid keyword stuffing
Turn SEO over to the experts
Chapter 18 Protecting Intellectual Property
Applying for a Patent
Know the types of patents
Utility patents
Design patents
Do your homework
Submit your idea
Know who owns the patent
Establishing a Copyright
Know what to include
Get your works copyrighted
Registering a Trademark
Use unregistered trademarks and service marks
Apply for a registered trademark
Part 5 The Part of Tens
Chapter 19 Ten Tips for Writing a Whitepaper
Consider Your Audience
Find Credible Sources
Include Facts and Figures
Follow a Simple Format
Create an Eye-Catching Cover
Pique Interest
Proofread and Edit Carefully
Conclude with a Call to Action
Maximize Mileage
Measure the Impact
Chapter 20 Ten Tips for Publishing in a Technical Journal
Don’t Procrastinate; Just Do It!
Hook Up with the Right Publication
Decipher the Masthead
Understand the Lingo
Write a Query Letter
Follow Up after Submitting Your Manuscript
Try Simultaneous Submissions
Don’t Stress about Confidentiality
Don’t Take No for an Answer
Take the Next Steps: When Your Article Is Accepted
Chapter 21 Ten Frustrations of Technical Writers
Work Overload and Time Pressures
Last-Minute Changes
Issues with Subject Matter Experts (SMEs)
Problems with Micromanagers
Challenges with New Products
Hardware and Software Challenges
Poorly Defined and Managed Projects
Poor Workspace Environments
Little or No Job Security
Burnout
Appendix A Punctuation Made Easy
Commas
Colons and Semicolons
Semicolons
Colons
Dashes and Parentheses
Dashes
Parentheses
Brackets
Other Punctuation
Quotation marks
Ellipses
Apostrophes
Possession
Omission
Hyphens
Question marks
Exclamation points
Periods
Slashes
Appendix B Grammar’s Not Grueling
Testing Your Grammatical Skills
Adjectives
Forms of adjectives
Absolute adjectives
Compound adjectives
Articles
Adverbs
Conjunctions
Correlative conjunctions
Subordinate conjunctions
Double Negatives
Nouns
Prepositions
Pronouns
Singular pronouns
Who and whom
Verbs
Gerunds
Dangling participles
Were and was
Subject and verb agreement
Answers to the Quickie Quiz
Appendix C Abbreviations and Metric Equivalents
Writing Abbreviations
Chemical elements
Postal abbreviations
Metric and U.S. Equivalents
Appendix D Tech Talk: Glossary of Terms
Appendix E Technical Writing Brief
About the Document
Learner Profile
Key Issues
Budget
Project Team
Milestones
Approval Cycle
Index
EULA