This document outlines the guidelines from Google's "Technical Writing One" course. Pass the raw Markdown into an LLM to assess your writing against these guidelines. GPT-3.5 may not process the full style guide effectively, but GPT-4 performs well when provided with clear prompts.

technical_writing_one_summary.md

Words

New or Unfamiliar Terms

• Link unfamiliar terms to existing explanations.
• Define new terms; group many definitions in a glossary.

Consistency

• Use terms consistently throughout.
• Shorten long-winded terms only after introducing them.

Acronyms

• Bold and spell out on first use, followed by acronym in parentheses (e.g., Telekinetic Tactile Network (TTN)).
• Use acronym consistently thereafter; avoid toggling with full term.
• Only define acronyms if they are much shorter and appear often.

Pronouns

• Introduce noun before its pronoun.
• Pronoun should be close to its noun (within 5 words).
• Reuse noun if a second noun intervenes before the pronoun.

Problem Pronouns

• Be cautious with it, they, them, their, this, and that.
• Clarify by replacing or following with the appropriate noun.

Active vs. Passive Voice

Active Voice

• Formula: actor + verb + target.
  • e.g., The cat sat on the mat.

Passive Voice

• Formula: target + verb (+ actor).
  • e.g., The mat was sat on by the cat.
• Some omit actor: e.g., The mat was sat on.

Identifying Passive Verbs

• Formula: form of be + past participle verb.
  • Forms of be: is/are, was/were.
  • Past participles: often end in ed (but some are irregular).
• Examples: was interpreted, is generated, is frozen by.

Imperative Verbs

• Are commands, often start items in lists.
  • e.g., Open the configuration file.
• Typically active; imply the actor is you.

Complex Sentences

• Can have mix of active and passive verbs.
  • Convert for clarity: "Python interprets code, but C++ compiles code."

Prefer Active Voice

• Easier for readers to process.
• Passive voice can obfuscate ideas or omit the actor.
• Active sentences are usually shorter.

Recommendation

• Use active voice predominantly. Be bold, be active.

Clear Sentences

Verbs

• Prioritize precise, strong, specific verbs.
• Limit generic verbs, especially forms of be, occur, and happen.
• Use varied verbs; don't over-rely on be.
• Generic verbs may signal passive voice or missing actors.

Reduce "There is/are"

• Eliminate There is or There are when possible.
• Replace with a meaningful subject and verb.
• Relocate the true subject and verb to sentence start.

Adjectives and Adverbs

• Use sparingly in technical writing.
• Avoid terms that sound like marketing.
• Convert vague adverbs/adjectives to objective data.
• Provide education, not sales material in tech docs.

Short Sentences

• Prefer short sentences for clarity.
• Keep one idea per sentence.
• Break complex sentences into multiple single-idea sentences.
• Convert long sentences with multiple items or choices into lists.

Extraneous Words

• Remove or replace unnecessary words or phrases.
• Examples:
  • Replace "at this point in time" with "now".
  • Replace "determine the location of" with "find".
  • Replace "is able to" with "can".

Subordinate Clauses

• Identify main and subordinate clauses in a sentence.
• Common indicators: which, that, because, whose, until, unless, since.
• Adhere to the one sentence = one idea rule.
• Split off-topic subordinate clauses into separate sentences.

That vs. Which

• In the U.S.:
  • Use "which" for nonessential clauses (preceded by a comma).
  • Use "that" for essential clauses (no comma before it).
• If there's a pause before the subordinate clause, use "which".
• If no pause, use "that".

Lists and Tables

List Types

• Bulleted list: For unordered items.
• Numbered list: For ordered items; sequence matters.
• Embedded list: Within a sentence; generally avoid.

List Guidelines

• Parallelism: Ensure grammar, category, capitalization, punctuation consistency.
• Numbered Lists: Preferably start with imperative verbs (commands).
• Punctuation:
  • If item is a sentence: Use sentence capitalization and end punctuation.
  • If not: Avoid sentence capitalization and end punctuation.

Table Guidelines

• Meaningful column headers.
• Limit text in cells; avoid >2 sentences per cell.
• Parallelism within individual columns.

Introductions

• Introduce lists and tables for context.
• Preferably use "following" in the introductory sentence.

Example

The following list identifies key parameters:

Paragraphs

Opening Sentence

• Most important sentence in a paragraph.
• Should establish the paragraph's central point.
• Avoid misleading the reader.

Single Topic Focus

• One paragraph, one topic.
• Remove or move sentences that don't relate to the topic.

Paragraph Length

• Avoid "wall of text" – break up long paragraphs.
• Don't make paragraphs too short; avoid many one-sentence paragraphs.

Answer Three Questions

• What are you communicating?
• Why is it important?
• How should it be used or understood?

Audience

Key Equation

• Good documentation = Knowledge/skills needed - Current knowledge/skills.

Define Audience

• Identify audience's role.
  • Examples: software engineers, technical managers, scientists, students, non-technical roles.
• Consider proximity to knowledge.
  • Knowledge differs within roles and over time.
  • Account for familiarity with related projects.

Determine Learning Needs

• List what the audience needs to learn or tasks to perform.
  • Sequence matters; foundational knowledge first.

Fit Documentation

Vocabulary & Concepts

• Match vocabulary to audience.
• Assume wider audiences need more explanation.
• Avoid curse of knowledge; experts can inadvertently omit vital context.

Language & Cultural Context

• Use simple words.
• Be culturally neutral; avoid cultural or regional idioms.
• Note: Translation software struggles with idioms and cultural references.

Documents

Scope

• Begin by defining the document's scope.
• Also define what the document doesn't cover (non-scope).
• Remove sections that don't align with scope.

Audience

• Explicitly state the document's target audience.
• Include any prerequisite knowledge, experience, or prior reading.

Introduction

• Answer essential questions at the start.
• Be prepared to revise the beginning multiple times.

Comparison

• Relate new ideas to concepts the audience understands.
• Use "similar to" and "except" for effective comparisons.

Audience Definition

• Define who the target audience is.
• Determine their goal and prior knowledge.
• Decide what they should know or do after reading.
• Organize the document based on the audience's needs:
  1. Overview: Describe main points and comparisons.
  2. Implementation: Include pseudocode and tips.
  3. Deeper Analysis: Discuss edge cases and uncertainties.

Punctuation

Commas

• Insert where readers would naturally pause.
• Separate items in an embedded list (use the Oxford comma for clarity).
• Use after a condition: "If X, (then) Y."
• Enclose definitions or digressions: "Python, an easy-to-use language, is popular."
• Avoid comma splices: use a period to separate independent thoughts.

Semicolons

• Unite highly related thoughts.
• Both sides of the semicolon should be complete sentences.
• Use commas for embedded lists, not semicolons.
• Place a comma after a transition following a semicolon: "X; however, Y."

Em dashes

• Represents a longer pause than a comma.
• Can replace commas or parentheses for emphasis or digression: "Language—often nicknamed code—is complex."

En dashes and Hyphens

• Em dash (—): Longest.
• En dash (–): Don't use (per Google Style Guide).
• Hyphen (-): Connect compound terms (e.g., "self-attention"). Check dictionary/style guide for complex compounds.

Parentheses

• Use sparingly for minor points or digressions.
• Period rules:
  • Entire sentence inside: period within (e.g., "(This is an example.)").
  • Ends a sentence, but not whole: period outside (e.g., "This is another (example).").