Word choice: vague/metaphorical language & jargon (closes #1, #22)

[d-morrison]

Summary

Adds two sections to the Word choice chapter (word-choice.qmd), complementing the existing Anglish/plain-words guidance.

Content

Avoid vague and metaphorical language (#1)

• Prefer the precise term for the quantity or mechanism you mean. Includes a comparison table using the issue's examples — "infection pressure" → "incidence rate", "disease burden" → "incidence rate, or prevalence proportion" — plus a note that the precise term makes a claim verifiable, and how to use a metaphor as a secondary aid when it genuinely helps intuition.

Minimize unnecessary jargon (#22)

• Use normal words in their usual sense; define genuinely-needed technical terms at first use and keep the same term rather than switching synonyms. Worked ❌/✅ example, and a two-question test for each technical word.

Conventions followed

• Appended as new ## sections without altering existing prose.
• Matches the chapter's existing style: semantic line breaks, Quarto #tbl-/#exm- environments, blank lines before lists.
• No new external links (avoids link-rot). Verified with quarto render --to html.

Closes

Closes #1, Closes #22.

🤖 Generated with Claude Code

---

Generated by Claude Code

[claude]

Code review in progress

• Gather context
• Read changed file and diff
• Review Quarto/prose correctness
• Review build hygiene
• Post inline comments
• Post summary

View job run

[claude]

Claude finished @d-morrison's task in 3m 14s —— View job

---

Code review

• Gather context
• Understand the request
• Read changed file and diff
• Review Quarto/prose correctness
• Review build hygiene
• Post inline comments
• Post summary

---

Summary

Overall this is a clean, well-scoped addition. The Quarto syntax is correct throughout:

• @tbl-vague-precise resolves to #tbl-vague-precise — cross-ref is valid ✅
• :::{#exm-jargon} with ## Replacing unnecessary jargon follows the callouty-theorem/custom-callout convention ✅
• Table caption placement (trailing paragraph inside the ::: block) matches the existing #tbl-latin-anglish-synonyms pattern ✅
• Semantic line breaks, blank lines before environments — all consistent with existing style ✅
• No build artifacts, no new dependencies, no navbar update needed (existing chapter) ✅

CI: All checks pass. The check-bibliography-dois failure is pre-existing and unrelated to this PR.

One content-logic issue posted as an inline comment: the two-question test at the end of the jargon section (lines 126–129) uses "both is no" as the replace condition, which leaves a gap — accessible-but-meaningless jargon (e.g., "leverage" for "use") wouldn't be caught. The test should either gate on Q2 alone, or change the condition to "either is no (with a carve-out for terms that need defining)."

---

To kick off another review pass after addressing the above:

@claude address review comments in [this review](https://github.com/d-morrison/psw/pull/34)

[claude]

Claude finished @d-morrison's task in 1m 11s —— View job

---

Review pass after sync

• Gather context
• Read updated file and diff
• Check if previous inline comment was addressed
• Post updated review

---

Summary

The sync commit (b19c1c7 Word choice: fix jargon test logic to gate on necessary meaning) fully resolves the one issue from the previous review.

Previous issue: The jargon two-question test used "both is no" as the replace condition, which let accessible-but-meaningless jargon (e.g. "leverage" for "use") slip through because Q1 would be YES.

Fix applied (lines 126–132): The two-question framing is gone. The test now gates the replace decision on a single question — does this term carry meaning a plain word would lose? — and uses accessibility only to decide define-vs-replace:

For each technical word, ask whether it carries meaning
that a plainer word would lose.
If it does not, replace it with the plainer word.
If it does carry necessary meaning
but a reader outside your subfield would not understand it,
define it clearly at first use.

This is exactly the "gate on Q2 alone" formulation suggested in the inline comment. The logic is now correct and covers the prototypical jargon case ("leverage" → "use": carries no extra meaning → replace ✅).

Everything else is unchanged and still clean:

• @tbl-vague-precise → #tbl-vague-precise cross-ref valid ✅
• :::{#exm-jargon} balanced, caption placement matches existing style ✅
• Semantic line breaks, blank lines before environments ✅
• No build artifacts, no new dependencies ✅

PR looks good to merge.

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://d-morrison.github.io/psw/pr-preview/pr-34/
Built to branch gh-pages at 2026-06-20 06:40 UTC. Preview will be ready when the GitHub Pages deployment is complete.