# The Elements of Technical Writing Book Study

Questions and notes to enhance your study of The Elements of Technical Writing (Goodreads, AbeBooks) by Thomas E. Pearsall.

TIP

Chapters 8-11 (The Formats of Technical Writing) are helpful for reference but are not particularly applicable for software development writing. They are not included in this document.

# Questions

# Preface-Chapter 1: Know Your Purpose

  1. What is technical writing?
  2. How does technical writing differ from other writing disciplines (e.g. popular nonfiction, advertising copywriting, etc.)?
  3. What are the two purposes of technical writing?
  4. Why is it important to have a purpose for your writing?

# Chapter 2: Know Your Audience

  1. What things should you consider when you visualize readers?
  2. What are some differences in writing for a stakeholder (executives) audience versus a developer (experts and technicians) audience?
  3. What are some differences between writing for a technician versus an expert?

# Chapter 3: Choose and Organize Your Content Around Your Purpose and Audience

  1. How much content should you write for your document?
  2. How do you choose what content to write?
  3. What are the three main ways to organize content in your document?
  4. Why should you create an outline?

# Chapter 4: Write Clearly and Precisely

  1. Why should you write without editing for the first draft?
  2. How often should you create a paragraph?
  3. How do you keep a reader's eyes on the subject?
  4. Why should you avoid inflated language?
  5. Why should you use the active voice most of the time?
  6. How many words per sentence is too much?
  7. How many words per sentence do professional writers average?
  8. Why should you write positively?
  9. What is parallelism?
  10. Why is parallelism important?

# Chapter 5: Use Good Page Design

  1. Why is good page design important?
  2. What are the important elements of good design?
  3. What do headings accomplish?
  4. What is the max level of headings you should use? Why?
  5. Why is more than four levels of headings too much?
  6. What function should headings perform?
  7. What should you not do with lists of informal tables? Why?
  8. How often should you use emphasis? Why?

# Chapter 6 - Think Visually

  1. Why do graphics play a major role in technical writing?
  2. What are some examples of visuals that developers use in technical writing?
  3. Graphics are used to communicate what three things?
  4. What are the two main ways to portray objects?
  5. What advantage do drawings have over photographs?
  6. In what way should you display data? Why?
  7. For what audience(s) should you use a graph?

# Notes

# Preface-Chapter 1: Know Your Purpose

  • What is technical writing?
    • Writing about subjects in technical disciplines
    • Technics: Theories, principles, arts, and skills (e.g. making a peanut butter and jelly sandwich, cooking Ramen noodles, etc.)
  • How does technical writing differ from other writing disciplines (e.g. popular nonfiction, advertising copywriting, etc.)?
    • Technical writing uses objective data instead of emotion to convince and persuade
  • What are the two purposes of technical writing?
    • To inform
    • To argue
  • Why is it important to have a purpose for your writing?
    • Like anything in life, your success and failure depends on purpose
    • "To be a successful writer, you must have a clear vision of what purpose you have for composing a given piece of writing."
    • Ask yourself, "What am I trying to accomplish? What goal do I have in writing this document? What is my objective? And what results do I want?"

# Chapter 2: Know Your Audience

  • What things should you consider when you visualize readers?
    • Concerns and characteristics
    • Education and experience (prerequisites are usually necessary)
    • Attitudes
  • What are some differences in writing for a stakeholder (executives) audience versus a developer (experts and technicians) audience?
    • High level vs. low level
    • Business impact vs. "how do I accomplish this task?"
    • Confidence in overall value and outcome vs. confidence in abilities
  • What are some differences between writing for a technician versus an expert?
    • Implementation vs. architecture
    • "How to lay a brick" vs. "How to architect a building"
    • "Get it done" vs. theory ("why" in addition to "what"—programming principles e.g. Single Responsibility Principle)
    • Overview vs. detailed how-to (e.g. getting stared guide)
    • The correct assumptions about your audience will make or break your writing.
    • If you assume too much, your audience will be confused. If you don't assume enough, your audience will be bored.
  • Quotes
    • “...few people approach using technical manuals with joy in their hearts.”
    • “...no one wants to read through unneeded information to get to needed information.”

# Chapter 3: Choose and Organize Your Content Around Your Purpose and Audience

  • How much content should you write for your document?
    • Enough to fulfill your purpose and meet your reader's needs...and no more!
    • Extra information can actually hinder the reader's goal
  • How do you choose what content to write?
    • By asking good questions
    • Framing the problem is "half the battle"
  • What are the three main ways to organize content in your document?
    • Topical
    • Chronological (events, step-by-step)
    • Classification (specific to general) and division (general to specific)
    • Mechanical Descriptions
  • Why should you create an outline?
    • To clarify your thoughts
    • An outline is a living document[^1]
    • It can change
    • Update it as you write
    • You can jump back and forth
    • Outlines are cheap, writing sentences are expensive
    • Outlines are like Test Driven Development (TDD)
  • Quotes
    • “..nothing is as important as choosing your content and organizing it around your purpose and audience.”

# Chapter 4: Write Clearly and Precisely

  • Why should you write without editing for the first draft?
    • Writing is thinking
    • First draft is a brainstorm—don't limit the brainstorm
    • Outlines are mutable
  • How often should you create a paragraph?
    • Every 60-100 words
  • How do you keep a reader's eyes on the subject?
    • Using intelligent repetition of key terms
    • Don't use variant terms
  • Why should you avoid inflated language?
    • Readers don't want to linger—get out of their way
    • Inflated language gets in their way (balloon in an alley)
  • Why should you use the active voice most of the time?
    • Clearly states the actor and the action
    • Passive voice is ambiguous—no one is taking responsibility
  • About how many words per sentence is too much?
    • 40-50
  • How many words per sentence do professional writers average?
    • 20
  • Why should you write positively?
    • Easier to understand what to do than what not to do
  • What is parallelism?
    • "Parallelism in grammar is defined as two or more phrases or clauses in a sentence that have the same grammatical structure."[^2]
  • Why is parallelism important?
    • Think of your document as a list of geometric shapes
    • If they are not parallel, your reader’s must do extract work to follow the progress
    • “Parallel sentence elements in grammar are just like parallel lines in geometry: they face the same direction and never meet.”[^2]

# Chapter 5: Use Good Page Design

  • Why is good page design important?
    • Increases the likelihood of careful reading
  • What are the important elements of good design?
    • Headings
    • Headers and footers
    • Appropriate text size/typefaces
    • List/informal tables
    • Discreet typographical emphasis
    • Whitespace
  • What do headings accomplish?
    • Lowers type density
    • Makes transitions easy
    • Improves accessibility
    • Gives you the ability to skip to desired part of document
  • What is the max level of headings you should use? Why?
    • 3 - 4
  • Why is more than four levels of headings too much?
    • Chops up document too much
    • Decreases accessibility
  • What function should headings perform?
    • Accurate identify sections of the document
    • Substantive vs. generic
  • What should you not do with lists of informal tables? Why?
    • Identify them with titles or table numbers
    • I don’t know…
  • How often should you use emphasis? Why?
    • Sparingly
    • Too much emphasis clutters the page

# Chapter 6 - Think Visually

  • Why do graphics play a major role in technical writing?
    • Can present data and ideas more efficiently and precisely than words
  • What are some examples of visuals that developers use in technical writing?
    • Architecture diagrams
    • Entity relationship diagrams
    • Code examples
  • Graphics are used to communicate what three things?
    • Objects
    • Processes
    • Data
  • What are the two main ways to portray objects?
    • Photographs
    • Drawings
  • What advantage do drawings have over photographs?
    • Control
  • In what way should you display data? Why?
    • Tables and graphs
    • Saves space
    • Summarizes data
    • Shows trends and relationships
  • For what audience(s) should you use a graph?
    • All of them

[^1]: Daniel Pink - Hubspot Academy, Writing Course With Bestselling Author Daniel Pink, Lesson 1
[^2]: Grammarly, Parallelism In Writing