tech-writer

name	tech-writer
description	Review and improve technical writing using Google Technical Writing course principles. Use when: editing docs, writing documentation, reviewing READMEs, improving clarity, fixing passive voice, restructuring sentences, reviewing technical content, writing API docs, creating tutorials, proofreading, tech writing review, documentation quality.
argument-hint	Paste or reference the text you want reviewed, or describe what you want to write

Technical Writing Review & Improvement

A skill based on Google's Technical Writing Course that reviews and improves technical documentation using proven principles from both Technical Writing One and Technical Writing Two.

Staging Directory

Use ~/.tech_writing_ghcp as a working directory for all tech writing operations:

• ~/.tech_writing_ghcp/drafts/ — Stage draft revisions of documents being reviewed
• ~/.tech_writing_ghcp/reviews/ — Store review notes and feedback for documents
• ~/.tech_writing_ghcp/cache/ — Cache intermediate analysis (e.g., audience profiles, scope statements)

Create the directory structure if it doesn't exist before performing any file operations:

mkdir -p ~/.tech_writing_ghcp/{drafts,reviews,cache}

When reviewing a document, write the annotated review to ~/.tech_writing_ghcp/reviews/<filename>-review.md and the improved version to ~/.tech_writing_ghcp/drafts/<filename>. This preserves the original and gives the user both a marked-up review and a clean improved draft to compare.

When to Use

• Reviewing or editing documentation, READMEs, tutorials, API docs, or design docs
• Writing new technical documentation from scratch
• Converting informal notes into polished technical writing
• Checking for clarity, voice, structure, and audience fit
• Restructuring large documents for better organization

Review Procedure

When reviewing a document, apply the following checks in order. Reference the course materials for detailed guidance on each topic.

1. Audience & Scope Check

Reference: Audience | Documents

• Is the target audience defined or identifiable?
• Is the document's scope clear? Is the non-scope stated where appropriate?
• Does the document match the audience's knowledge level?
• Does it suffer from the curse of knowledge?
• Is the language culturally neutral and free of idioms?

2. Words & Terminology

Reference: Words

• Are new or unfamiliar terms defined on first use?
• Are terms used consistently throughout (no unannounced synonyms)?
• Are acronyms introduced properly (full term + acronym in bold on first use)?
• Are pronouns unambiguous? (Check every instance of "it", "they", "this", "that")

3. Active Voice

Reference: Active Voice

• Identify all passive voice sentences
• Convert passive to active where possible (actor + verb + target)
• Flag any passive sentences that omit the actor entirely
• Leave passive voice only where it genuinely serves the sentence better

4. Clear & Short Sentences

Reference: Clear Sentences | Short Sentences

• Replace weak verbs (forms of "be", "occur", "happen") with strong, specific verbs
• Eliminate "There is" / "There are" sentence openers
• Ensure each sentence focuses on a single idea
• Eliminate extraneous words and bloated phrases
• Reduce or split sentences with excessive subordinate clauses
• Check that/which usage (that = essential, which = nonessential with comma)
• Replace subjective adjectives/adverbs with objective data where possible

5. Lists & Tables

Reference: Lists and Tables

• Convert embedded lists into bulleted or numbered lists
• Ensure list items are parallel (grammar, category, capitalization, punctuation)
• Use numbered lists for ordered items, bulleted for unordered
• Start numbered list items with imperative verbs
• Ensure every list and table has an introductory sentence ending with a colon

6. Paragraphs

Reference: Paragraphs

• Check that each paragraph opens with its central point
• Ensure each paragraph focuses on a single topic
• Flag paragraphs that are too long (>7 sentences) or too short (1 sentence)
• Verify paragraphs answer what, why, and how

7. Document Structure (for longer documents)

Reference: Large Docs | Editing

• Does the document start with a summary of key points?
• Are headings task-based and descriptive?
• Is there text under each heading (no heading immediately followed by sub-heading)?
• Does the document progressively disclose information?
• Is navigation clear (TOC, links, logical flow)?

8. Sample Code (if applicable)

Reference: Sample Code

• Is sample code correct, concise, and understandable?
• Are comments focused on non-obvious aspects?
• Does the document explain how to run the sample code?
• Are examples sequenced from simple to complex?
• Are anti-examples shown where helpful?

9. Illustrations (if applicable)

Reference: Illustrations

• Do illustrations have brief, takeaway-focused captions?
• Is each illustration constrained to one concept?
• Are visual cues (callouts, highlights) used to focus attention?
• Would adding an illustration improve comprehension?

10. Punctuation & Formatting

Reference: Punctuation | Markdown

• Check comma usage (serial commas, condition-consequence, comma splices)
• Check semicolon usage (only between complete, highly related sentences)
• Check colon usage before lists
• Verify Markdown formatting is correct

Writing New Documents Procedure

When helping write new documentation:

1. Define the audience — Identify roles, proximity to knowledge, prerequisite skills
2. Define the scope — What the document covers and does not cover
3. Create an outline — Structure topics logically, explain before asking the reader to act
4. Write an introduction — Cover what, prior knowledge, and non-scope
5. Draft content — Apply all principles above while writing
6. Self-review — Run the Review Procedure above on your own draft

Stage all working files in ~/.tech_writing_ghcp/ during this process.

LLM-Assisted Writing Tips

Reference: LLMs in Technical Writing

When using LLMs to assist with technical writing:

• Specify a role, target audience, document type, and goal in prompts
• Add constraints to reduce hallucinations
• Provide context (source code, transcripts, existing docs)
• Fix organizational issues before grammar/style issues
• Always verify LLM output for factual accuracy
• Remember: clear technical writing is the byproduct of clear technical thought

Quick Reference Checklist

Use this checklist for fast reviews:

• Audience defined and matched
• Terms consistent and defined
• Acronyms properly introduced
• Pronouns unambiguous
• Active voice predominant
• Sentences short and focused (one idea each)
• Strong verbs used (minimal be/occur/happen)
• No "There is/are" openers
• Lists parallel and properly typed
• Lists and tables introduced with context
• Paragraph openers establish the topic
• Paragraphs 3-5 sentences
• Document starts with key summary
• Headings are task-based
• Sample code is correct, concise, commented
• Illustrations have captions and focus
• Punctuation correct (Oxford commas, no comma splices)