Stop Writing Code, Start Writing Docs: A Playbook for Writers Leading AI Work
Google's Keith Ballinger put it bluntly: to go faster with AI, slow down and write better docs. Clear guides for AI agents, solid architecture, and a simple project plan beat frantic coding every time.
If you're a writer, this is your lane. Agents follow language. The person who writes the brief sets the quality bar.
Why docs beat code for AI agents
- Agents need context, constraints, and examples more than functions. Your words are the system.
- Documentation scales across tools. Swap a model or platform and your process still stands.
- Good docs reduce rework. Fewer rewrites, fewer surprises, fewer "fix later" loops.
The writer's edge: turn briefs into agent instructions
Think of an AI agent as a junior teammate. It needs a brief, a standard, and a definition of "done."
- Goal: what outcome is expected (not just "write an article").
- Audience: who it's for and what they need to know first.
- Voice and style: tone rules with short examples.
- Format: headings, length, links allowed, assets required.
- Sources: approved references, internal docs, retrieval rules.
- Constraints: topics to avoid, banned phrases, compliance needs.
- Acceptance tests: 3-5 checks that confirm the draft is usable.
Architecture first: map the content system
Before touching prompts, map how work flows. Simple diagram, clear handoffs.
- Inputs: briefs, brand voice, datasets, style guides.
- Agents: research, outlining, drafting, editing, fact-checking, formatting.
- Tools: where retrieval happens, where versions live, who approves.
- Outputs: article, social cutdowns, newsletter blurb, metadata.
- Feedback loop: what triggers revisions and how they're logged.
A one-page architecture reduces confusion more than any prompt tweak.
Project plan: small, boring, effective
- Milestones: outline → draft → review → publish → repurpose.
- Owners: human vs. agent per step. No fuzzy roles.
- Versioning: naming rules, where the truth lives.
- Deadlines: timeboxes for each stage, including review SLA.
- Quality gates: acceptance tests at outline and draft stages.
Agent brief template (steal this)
Copy this into your tool of choice and fill the blanks.
- Role: You are a [researcher/editor/drafter] supporting [project].
- Goal: Produce a [format] for [audience] that [business outcome].
- Voice: [3 bullets], Example lines: "[line 1]", "[line 2]".
- Scope: Include [topics]. Exclude [topics/banned terms].
- Sources: Use only [links/docs]. If missing, ask for approval.
- Process: 1) Propose outline, 2) Wait for approval, 3) Draft, 4) Self-check with tests.
- Acceptance tests: Must pass [fact accuracy], [link policy], [style], [originality threshold].
- Output format: [headings], [word count], [internal links], [CTA].
For developers, it's tools. For writers, it's standards
Ballinger's team works on Gemini CLI, positioned against agentic coding tools like Claude Code. The lesson for writers: tools change, standards earn their keep.
- Create a single source of truth: brand voice doc, link policy, style rules, examples.
- Keep reusable prompts and briefs in a living library, versioned like code.
- Document review notes so agents improve with each task.
Common mistakes (and easy fixes)
- Vague briefs → Add acceptance tests and examples.
- Too many prompts → Consolidate into one structured instruction set.
- No source control → Treat docs like product: version, diff, and approve.
- Skipping outline review → Lock structure first; drafts move faster.
- One-off work → Plan repurposing upfront (newsletter, social, SEO variants).
Week-one rollout plan
- Day 1: Draft your brand voice, link policy, and forbidden phrases.
- Day 2: Build the agent brief template and an outline acceptance test.
- Day 3: Map your pipeline (inputs → agents → outputs → feedback).
- Day 4: Run one article end-to-end with strict gates.
- Day 5: Debrief, refine docs, and publish your standards.
Helpful references
- Google Engineering Practices: Design Docs - great structure for planning work.
- AI tools for copywriting - see what's working across the market.
The short version
Write docs like they're the product. Define the work, the rules, and what "done" means. Agents will follow your lead, and your team will move faster with fewer do-overs.
Your membership also unlocks:
