Tom Johnson's AI-Assisted Technical Writing Workflow

Table of content
Tom Johnson's AI-Assisted Technical Writing Workflow

Tom Johnson is a technical writer at Google based in Seattle. He runs I’d Rather Be Writing, one of the longest-running technical writing blogs, and hosts a popular API documentation course. His writing on AI workflows has become required reading for technical communicators adapting to LLM tools.

Johnson reports roughly doubling his productivity since incorporating AI into his documentation workflow. His approach treats AI as a power tool requiring skilled direction rather than an autonomous writer.

Background

The Iterative Workflow

Johnson’s methodology rejects the “magic button” approach to AI writing. Instead, he breaks documentation tasks into discrete steps:

  1. Gather source material. Record engineer interviews, collect internal docs, pull code samples. The quality of inputs determines output quality.

  2. Distill with AI. Feed 100+ pages into large-context models (700K+ tokens). Ask for summaries, extract key concepts, identify gaps.

  3. Generate section by section. Don’t ask for complete documents. Work through outlines one topic at a time.

  4. Apply chain of thought. Separate evaluation from action. First ask AI to identify issues, then fix them in a second pass.

  5. Review and iterate. Multiple cycles for factual accuracy, technical correctness, and editorial quality.

From his April 2024 blog post: “The more you can decompose complex processes into discrete steps, the outcome will be better.”

Use Cases for Documentation

Johnson identifies ten areas where AI adds genuine value for technical writers:

Use CaseApplication
Code comprehensionExplain what unfamiliar code does
Bug thread distillationExtract actionable updates from long discussions
Content summarizationCondense lengthy source material
Grammar and styleGet second opinions on unclear sentences
Information typingRestructure content into standard patterns
API comparisonFind discrepancies between specs and responses
Glossary draftingGenerate initial definitions for technical terms
Build scriptsWrite automation for publishing workflows
Data synthesisFind patterns across granular feedback

His AI-powered documentation section covers each in depth with practical prompts.

Human-in-the-Loop Philosophy

Johnson positions AI as collaborative rather than autonomous. Documentation requires context that AI lacks: organizational priorities, audience needs, what’s been tried before, political sensitivities.

Key principles from his writing:

AI excels at voiceless, explanatory content. Documentation written in neutral third person suits AI well. Experience-driven or opinion pieces don’t.

Raw output is insufficient. First drafts need substantial editing. The time savings come from faster iteration, not skipped steps.

Prompt engineering isn’t obvious. Many writers struggle despite AI’s clear potential. Success requires learning to guide the tool.

From December 2023: “My central argument is that AI use cases are so ubiquitous they apply to all facets of life.”

Tools and Setup

Johnson primarily uses:

He emphasizes matching tools to tasks. Large context windows matter for digesting engineering docs. Creativity matters for blog posts. Grammar checking needs different strengths.

The AI Book Club

Johnson co-hosts monthly discussions on AI-related books at idratherbewriting.com. Recent reads include Ethan Mollick’s Co-Intelligence, Karen Hao’s Empire of AI, and Yuval Noah Harari’s Nexus.

The club reflects his broader approach: treat AI as a subject worth studying, not just a tool to use.

Key Takeaways

PrincipleImplementation
Task decompositionBreak docs into sections, process individually
Chain of thoughtEvaluate first, then fix
Source qualityBetter inputs yield better outputs
Human reviewMultiple passes for accuracy
Tool matchingDifferent AI tools for different tasks

Next: Simon Willison’s Workflow

Topics: workflow prompting ai-coding automation