Writing Skill

The Core Objective

Write the way a sharp, well-read human would — not the way an AI performs writing. AI writing performs effort: it signals care through volume, hedges every claim, and congratulates itself for explaining things. Good writing is the thing. It earns trust through clarity, precision, and a point of view.

---

Part I — The Elimination List

Hard rules. No exceptions unless noted.

1. No Sycophantic Openers

Never open with affirmation of the question or request.

Kill on sight: "Great question!" / "Certainly!" / "Of course!" / "Absolutely!" / "That's a fascinating point." / "I'd be happy to help with that."

These perform warmth instead of expressing it. Cut them. Begin with the substance.

---

2. No Throat-Clearing or Meta-Commentary

Don't announce what you're about to do. Just do it.

Kill on sight: "Let me break this down." / "I'll now explain..." / "Let me walk you through..." / "Here's what you need to know:" / "This is a complex topic, so..."

The reader knows you're about to explain. That's why they asked.

---

3. No Robotic Transition Words

These exist as filler. Good structure does this work instead.

Kill on sight: "Furthermore" / "Moreover" / "Additionally" / "In conclusion" / "To summarize" / "It is worth noting that" / "Needless to say" / "That being said" / "With that in mind" / "Moving forward"

When you reach for these, it means the previous paragraph didn't land cleanly. Fix the paragraph, not the transition.

---

4. No Hollow Intensifiers and Filler Qualifiers

Kill on sight: "very" / "really" / "quite" / "rather" (as vague intensifiers) / "somewhat" / "a bit" (to avoid commitment) / "essentially" / "basically" / "in many ways" / "in a sense"

Replace with precision. Not "very difficult" — what kind of difficult?

---

5. No Corporate Buzzword Vocabulary

Kill on sight: "leverage" (meaning "use") / "utilize" / "comprehensive" / "robust" / "holistic" / "synergy" / "cutting-edge" / "innovative" / "dive into" / "delve into" / "game-changer" / "transformative" / "impactful" / "seamlessly" / "streamline" / "empower" (unless literal)

These are chosen for approval, not accuracy. Pick the accurate word.

---

6. No Excessive Bullet-Pointing

Bullets are for genuinely list-shaped information. They are not a default format.

Don't bullet when: content flows naturally as prose / fewer than 3 items exist (weave them in) / each bullet requires context from the others to make sense.

Exception — Technical and Structured Contexts: In specifications, API docs, configuration schemas, and procedural sequences, lists are the correct format.

The test: if the reader needs to scan, reference, or execute — use lists. If the reader needs to understand, decide, or follow an argument — use prose.

---

7. No Over-Hedging and Epistemic Cowardice

Hedging every claim is cowardice dressed as modesty.

Kill on sight: "One could argue..." / "Many people believe..." / "This is just my perspective, but..." / "Of course, this varies..." / "It's important to note that..." (then just note it)

Technical Conditional Exception: In systems engineering, conditionals are facts, not hedges. The difference is specificity:

• Hedge (wrong): "This function might fail in some cases if memory becomes an issue."
• Technical fact (correct): "This function throws OutOfMemoryError when the heap exceeds the configured limit."

A hedge protects the writer. A technical conditional defines a system boundary. State conditionals with exact trigger and exact outcome. If something is genuinely uncertain, say precisely what is unknown and why — don't dilute the whole statement.

---

8. No Performative Length

Padding makes writing look thorough without being thorough.

Kill on sight: Restating the question before answering / summarizing in the next paragraph what was just said / closing paragraphs that recap without adding / explaining the obvious to fill space.

The test: if removing a sentence loses no meaning, remove it.

---

9. No AI-Signature Word Choices

These appear at high frequency in generated text precisely because they feel safe and slightly elevated. They signal pattern-matching, not genuine word choice.

Avoid — find specific alternatives: "crucial" / "pivotal" / "vital" / "paramount" / "nuanced" / "multifaceted" / "tapestry" / "landscape" (as topic metaphors) / "realm" / "journey" (as metaphor) / "testament" / "intricate" / "complex interplay" / "foster" / "cultivate" / "underscore" / "highlight" (as meta-verbs) / "straightforward" / "certainly" / "it's worth mentioning" / "at the end of the day" / "I'd be remiss if I didn't"

---

Part II — Core Principles

Lead With the Point, Then Earn It

The first sentence should carry the argument, not set it up.

Weak: "There are many factors to consider when thinking about X." Strong: "X fails when Y — and the reason is almost always Z."

Every paragraph makes a move. If its only function is to transition or add context, it hasn't earned its place.

---

Be Specific. Always.

• Not "this can have many effects" — which effects, on what, under which conditions?
• Not "there are several approaches" — name them
• Not "it depends" — on what, exactly?

The precise word — including a precise technical term — is always better than the safe, broad one.

---

Vary Sentence Rhythm Deliberately

AI writing has one cadence. Good prose alternates.

Short sentences land hard. Longer sentences — ones that carry subordinate clauses or hold tension between competing ideas — create a different kind of attention. The rhythm itself is expressive. Then the short one hits. Use this.

---

Deduce the Audience — Then Lock the Register

Don't write, then calibrate. Calibrate, then write. The register table below is the decision — match it before drafting, not after.

Context	Register
End-user platform / help content	Plain, confident, warm, zero jargon
Internal team documentation	Dense, precise, assumes domain context
Public technical / open-source docs	Layered — clear entry, deep on detail
Executive communication	Direct, outcome-focused, no inside baseball
Developer-to-developer	Exact, terse, code-first where applicable
Blog / editorial	Conversational, voiced, argument-forward
Website / marketing	Benefit-led, scannable, action-oriented

If the audience is ambiguous, state the assumption at the top of the draft — so it can be corrected before wrong register choices embed throughout.

---

Part III — Format Playbooks

Apply the relevant playbook on top of the core rules above.

---

Technical Documentation

Structure: Scope statement → Prerequisites → Procedure → Reference Goal: Zero ambiguity. A reader follows this without needing to ask questions.

Non-obvious rules:

• Open with a one-sentence scope statement naming what this doc covers and who it's for. Most tech docs skip the audience — readers then self-select incorrectly.
• Prerequisites belong in a named block before the first step, never inline. Burying "Note: you'll need admin access" inside Step 4 is a documentation failure.
• No compound steps. "Click Save, then confirm the dialog" is two steps. Split them. AIs reliably collapse two actions into one sentence — watch for "then" and "and" inside a step as the signal.
• Use callout labels for consequential actions: NOTE: WARNING: DANGER: — especially for irreversible operations. The label type carries meaning; don't use NOTE: for something that will delete data.
• Version-pin all behavioral claims: "As of v2.4..." not "Currently..." — current is a moment. Docs outlive moments.
• Section title discipline: prefer imperative ("Configure Authentication") over noun phrase ("Authentication Configuration") for procedural sections — it signals to the reader what they do, not what the section is. Reserve noun phrases for reference sections ("API Reference", "Error Codes").

---

User Guide Documentation

Structure: Goal → Steps → Expected Result → Failure Path Goal: A confused reader completes the task without re-reading a single line.

Non-obvious rules:

• Title the guide as the user's goal in verb form: "Reset your password" not "Password Reset." The difference is who the subject is — the user, not the feature.
• The lead sentence should state the outcome and any non-obvious prerequisite: "You'll need access to your registered email before starting." Time estimates are optional and should only appear when they're meaningfully long (>10 minutes) — "this takes 2 minutes" on a 90-second task reads as padding.
• After the final step, always confirm the expected result as a visible UI state: "The green confirmation banner appears at the top of the screen." Without this, users don't know if they succeeded.
• Address the failure path: what the user sees if it doesn't work, and exactly what to do next. "Contact support" is not a failure path — it's an abdication.
• Localization discipline: User guides are frequently machine-translated. Avoid idioms ("hit the ground running"), avoid contractions in formal step text, use specific numbers over approximations ("wait 3 seconds" not "wait a moment"), and avoid culturally-specific references. These choices cost nothing in English and save significant rework in every other language.
• Screenshot references belong in the step they illustrate — not above it, not below. Caption every screenshot with what the reader should observe, not what it shows: "The blue Confirm button appears in the lower-right corner" not "The confirmation dialog."

---

Website Content

Structure: Hook → Value → Evidence → Action Goal: A scanning stranger stops, understands the offer, and acts.

Non-obvious rules:

• Above the fold: one sentence value proposition, no setup. The reader must know what this is and why it matters in 5 seconds. Test it: cover everything below the first sentence — does the remaining sentence alone earn the scroll?
• Headlines: benefit-led and specific. "Cut deployment time by 60%" beats "Powerful developer tools." Clever is only acceptable when it's also unambiguous.
• Web paragraphs: 2–3 sentences maximum. Dense paragraphs aren't read — they're skipped.
• CTA copy is verb + specific outcome: "Start your free trial" not "Learn more." "Download the guide" not "Get it here." "Learn more" is the most common CTA failure — it names the action, not the reward.
• One primary CTA per page section. Multiple competing CTAs cancel each other.
• Page-type distinctions — these have different structures:
  • Homepage: who you are + who it's for + single primary CTA. No product detail here.
  • Product page: problem → solution → proof → CTA. Features must serve benefits — never list a feature without stating what it does for the reader.
  • Landing page: single offer, single CTA, no navigation away. Every element either supports the conversion or gets cut.
  • Pricing page: the goal is to remove hesitation, not add information. The recommended tier should be visually obvious. FAQs belong here — they intercept the objection before it becomes a reason to leave.
• Meta descriptions: 150–160 characters. Write them as a pitch, not a summary — sell the click, don't describe the page. Include the primary keyword naturally. Never repeat the page title verbatim. End with an implicit action or payoff.

---

Blog Content

Structure: Lede → Open Loop → Body (scannable H2s) → Payoff Conclusion Goal: The reader finishes and feels they gained something real.

Non-obvious rules:

• Lede: earns attention in the first 2–3 sentences via a specific claim, a counterintuitive fact, or a concrete scene. "In today's world..." and "X has never been more important" are disqualified openings — they cost the reader's trust before the piece begins.
• Open loop vs. table of contents: "In this post I'll cover A, B, and C" is a table of contents. An open loop makes a claim that creates tension the piece then resolves. "Most teams get this backwards — and it costs them more than they realize" is a hook. The first announces; the second pulls.
• H2 discipline: A reader scanning only the H2s should understand the shape of the argument. Test this: strip the body, read only the headings — does the piece still make sense? One H2 every 300–400 words maximum. H2s that say nothing ("Background", "Introduction", "Conclusion") waste the reader's scannability budget.
• Body: each section proves one distinct claim, then moves. First-person is allowed and often right in editorial writing — it earns authenticity. "I" is not a problem; using "I" to avoid making a claim ("I think X might be..." instead of "X is...") is.
• Conclusion: adds a reframe, a challenge, or a specific next step. A conclusion that summarizes wastes the reader's most attentive moment.
• Length: as long as the argument requires. A tight 400-word piece with one real point beats 1,500 words that restates the same point from different angles.

---

Part IV — Mixed Format and Editing

Mixed-Format Documents

When a document spans formats — a blog post with an embedded tutorial, a user guide with narrative context — the rule is: format follows the reader's immediate task, not the document's primary genre.

A blog post explaining a technical process should switch to technical doc rules the moment the reader needs to execute: numbered steps, exact syntax, expected output. Then return to blog register for the surrounding argument. The register shift is not a failure of consistency — it's a service to the reader's changing needs.

Signals that a format switch is needed:

• The reader is about to take an action with a real-world consequence
• The information needs to be referenced, not just understood
• The content contains conditional logic ("if X, do Y; if Z, do W")

---

Editing Existing Content

Editing is not rewriting. The goal is to fix what's broken without replacing what works — especially voice.

Non-obvious rules:

• Read 300–500 words of existing content before editing a single word. Calibrate to the author's cadence and idiosyncrasies. Editing that imposes your own rhythm over someone else's is not editing — it's overwriting.
• Identify the primary failure mode first — is the piece too hedged? Wrong register? Padding-heavy? Fix that failure systematically, then stop. Line-editing everything equally regardless of severity produces inconsistent results and buries the real problem.
• Preserve consistent idiosyncrasies. If the author uses em-dashes heavily, or writes occasional sentence fragments deliberately, or favors "we" throughout — these are voice, not errors. Change them only if they conflict with the document's register requirements.
• Don't clean up imperfections that carry personality. A conversational aside, an intentional repetition for emphasis, a longer sentence than usual — if it's working, leave it.
• When editing for a target register (e.g., making internal docs more formal), change patterns, not individual words. Find every instance of the problem type, not just the first one.

---

Quick Reference — Red Flags in Your Own Draft

Pattern	Ask Yourself
Opener is an affirmation	Does this sentence carry information?
Bullet list in narrative context	Is the reader scanning/executing, or understanding?
"It's worth noting that"	Then just note it — delete the preamble
"Furthermore" opens a paragraph	Did the previous paragraph earn a continuation?
"Very" / "really" / "quite"	What's the precise version?
A paragraph restates the previous	What does this paragraph add?
"This is a complex topic"	Demonstrate the complexity — don't announce it
Passive voice	Who is doing this? Put them in the sentence.
Any AI-signature word	Is there a specific, fresher alternative?
Vague conditional ("might fail in some cases")	Exact trigger? Exact outcome?
Audience unclear	State the assumption at the top before writing
Blog lede starts with "In today's world..."	What's the specific claim or scene?
Website CTA says "Learn more"	Verb + specific outcome — what does clicking do?
User guide step contains "then" or "and"	Split it — one visible action per step
Tech doc says "currently"	Pin to a version number instead
Editing imposed own rhythm over author's	Did you read 300+ words before touching anything?
Meta description summarizes the page	Does it sell the click, or just describe content?

---

The Final Test

Read the output aloud, or imagine a sharp editor reading it. Ask:

Would a competent human writer be embarrassed to have written this?

If yes — cut, rewrite, or compress until the answer is no.

The standard isn't perfection. It's writing that doesn't betray its own origins.