write-better

Writing guidance for AI agents

Write so the reader understands the point, the evidence, and the next action without rereading. Protect the reader's attention. Prefer plain language, concrete details, and useful structure.

1. Start with the useful part

Put the main point in the first one or two sentences.

For professional communication, lead with one of these:

• the request
• the decision
• the conclusion
• the result
• the problem
• the relevant fact

Add context after the reader knows why they are reading.

Bad:

I wanted to reach out to provide some context regarding the project timeline.

Better:

The release will move from May 12 to May 19 because the payment tests are still failing.

Brief context may come first when the reader needs it to interpret sensitive, legal, safety-related, or surprising information correctly.

2. Make every sentence earn its place

Every sentence should change what the reader knows, decides, or does.

A sentence may contribute:

• a fact
• a definition
• a reason
• evidence
• a condition
• a constraint
• a consequence
• an exception
• a warning
• a decision
• an action
• a concrete example

Delete sentences that only announce, emphasize, summarize, or decorate a point already made.

Common filler:

• "That distinction matters."
• "It is important to note that..."
• "The practical mental model is simple."
• "This highlights the importance of..."
• "Here is what you need to know."
• "In today's rapidly changing environment..."
• "At its core..."
• "The real question is..."

State the information instead.

3. Preserve information, not length

Keep the original facts, requirements, qualifications, and necessary examples.

You may:

• delete empty sentences
• merge paragraphs
• remove repeated explanations
• shorten examples
• reorder information
• replace abstractions with concrete language

Do not preserve the original paragraph count or sentence count. A padded five-paragraph draft may need to become two paragraphs.

4. Use plain language

Prefer familiar words and direct constructions.

Use:

• "use" instead of "utilize"
• "help" instead of "facilitate"
• "improve" instead of "enhance"
• "use" instead of "leverage"
• "is" instead of "serves as"
• "has" instead of "boasts"
• "can" instead of "has the ability to"

Treat these words as warnings:

delve, leverage, robust, seamless, streamline, utilize, comprehensive, holistic, facilitate, optimize, harness, navigate, landscape, realm, foster, empower, crucial, essential, pivotal, significantly

Keep one when it has a precise technical meaning. Remove it when it adds polish without precision.

Good:

The compiler optimizes repeated lookups.

Weak:

The platform optimizes the customer journey through seamless automation.

5. Be concrete

Use names, dates, numbers, owners, systems, and observable actions.

Weak:

We should improve cross-functional alignment to streamline delivery.

Better:

Priya will send the revised API schema to the mobile team by Tuesday. The team will confirm the migration date by Thursday.

Prefer language the reader can picture happening.

Replace abstract nouns with actions when possible:

• "conduct an evaluation of" becomes "evaluate"
• "make a determination" becomes "decide"
• "provide assistance" becomes "help"
• "perform an inspection" becomes "inspect"

6. Put actions in usable form

For requests, specify:

• who should act
• what they should do
• when it is due
• what completion looks like

Weak:

Let me know your thoughts.

Better:

Please confirm the revised launch date by Thursday at 3 p.m.

Prefer one main outcome per message. Several related actions may appear together when each one is explicit. Number them when order, ownership, or completion matters.

7. Match the genre

Clarity does not require the same voice everywhere.

For documentation:

• describe current behavior
• explain how to use it
• state constraints and failure conditions
• include examples only when they remove ambiguity
• avoid promotional language and personality

For workplace messages:

• use the tone appropriate to the relationship
• keep politeness brief
• make the request easy to identify
• avoid unnecessary formality

For essays and personal writing:

• preserve genuine opinions, uncertainty, humor, and irregularities
• do not manufacture quirks to appear human
• do not add tangents, fragments, or fake self-corrections unless they belong to the author's voice

Match the genre before matching stylistic mannerisms.

8. Preserve the author's voice

When a writing sample is available, study:

• sentence length
• vocabulary
• paragraph openings
• punctuation
• degree of formality
• transition habits
• humor
• recurring phrases

Keep meaningful irregularities. Do not replace the author's voice with a generic casual style.

Do not add personality merely to signal that a human wrote the text.

9. Avoid rhetorical packaging

Do not turn ordinary information into slogans, aphorisms, or miniature speeches.

Avoid formulas such as:

• "It is not X. It is Y."
• "It is not just about X. It is about Y."
• "X is the language of Y."
• "X becomes a trap."
• "The future of X is Y."
• "What really matters is..."
• "The heart of the matter is..."

Use corrective contrast only when the reader is likely to hold the mistaken belief and correcting it affects their actions.

Weak:

This is not merely a performance improvement. It is a transformation of the developer experience.

Better:

The change reduces build time from 11 minutes to 4 minutes.

10. Do not manufacture emphasis

Avoid unsupported claims that something is important, significant, pivotal, profound, or transformative.

Explain the consequence.

Weak:

This is a crucial change for the organization.

Better:

Without this change, the company cannot process EU customer data after September 1.

The facts should carry the emphasis.

11. Control metadiscourse

Metadiscourse tells the reader how to interpret the writing rather than giving them the information.

Common forms:

• "This means..."
• "That distinction..."
• "In other words..."
• "It is worth noting..."
• "The key point..."
• "As we can see..."
• "Let us explore..."
• "Now let us look at..."

Use these only when they resolve a real structural ambiguity. Do not place them at the start of each paragraph to create artificial continuity.

Check paragraph openings that begin with "This" or "That." Make sure the paragraph advances the explanation rather than renaming the previous one.

12. Avoid semantic repetition

Do not repeat a claim merely with different vocabulary.

A restatement should add at least one of these:

• greater precision
• a necessary example
• a consequence
• a limit
• an exception
• an operational instruction

Delete paraphrase chains that explain the same point several times.

13. Use lists only when the structure helps

Use a list when the reader needs to:

• compare items
• follow steps
• check requirements
• identify owners
• scan options

Do not force ideas into groups of three. Do not add a third item for rhythm or completeness.

Avoid long lists with bold labels when a sentence or table would be easier to read.

14. Let sentence structure follow the information

Avoid a uniform run of medium-length sentences. Also avoid forced alternation between short and long sentences.

Do not add fragments or dramatic pauses merely to vary the rhythm.

Read the passage aloud. Revise it when:

• every sentence has the same shape
• clauses arrive in repeated groups of three
• each paragraph ends with a punchline
• several short sentences manufacture drama
• the prose ticks with an obvious pattern

Sentence length should reflect the amount and relationship of the information.

15. Use direct subjects and verbs

Name the actor when responsibility matters.

Weak:

The request was reviewed and a decision was made.

Better:

The security team reviewed the request and rejected it.

Passive voice is acceptable when the actor is unknown, irrelevant, already understood, or less important than the process.

Acceptable:

Tokens are deleted after 30 days.

The problem is unclear responsibility, not passive grammar itself.

16. Do not cycle through synonyms

Repeat the correct term when precision matters.

Weak:

The customer submits a request. The user then receives a response. The account holder can review the result.

Better:

The customer submits a request, receives the response, and reviews the result.

Technical writing benefits from stable terminology.

17. Remove fake depth

Watch for participial phrases that add interpretation without evidence:

• highlighting
• underscoring
• reflecting
• showcasing
• symbolizing
• fostering
• contributing to
• ensuring

Weak:

The redesign uses blue and green, reflecting the company's commitment to trust and growth.

Better:

The redesign uses blue and green. The design brief identifies them as the company's existing brand colors.

Do not infer symbolism, intention, or significance without a source.

18. Avoid vague authority

Do not write:

• "Experts say..."
• "Observers have noted..."
• "Industry reports suggest..."
• "Critics argue..."
• "Research shows..."

Name the source and state the finding.

Better:

In its 2025 survey of 640 developers, Stack Overflow found that 42 percent checked AI-generated code less carefully when working under deadline pressure.

When no reliable source exists, remove the claim or state the uncertainty plainly.

19. Avoid promotional language

Documentation and factual writing should not sound like advertising.

Remove phrases such as:

• groundbreaking
• vibrant
• breathtaking
• renowned
• world-class
• powerful and intuitive
• rich history
• commitment to excellence
• exciting journey
• bright future

Replace praise with observable details.

Weak:

The platform delivers a seamless and powerful experience.

Better:

The platform imports CSV files up to 2 GB and reports row-level validation errors.

20. Use punctuation plainly

Do not use em dashes.

Replace them with:

• a period for a separate thought
• a comma for a short interruption
• a colon for an explanation
• parentheses for a true aside

Do not use punctuation to manufacture drama.

Preserve conventional en dashes only when the applicable style guide requires them for ranges or compound relationships. A house style may replace those too.

21. Keep formatting functional

Avoid:

• mechanical boldface
• emojis in professional headings
• title case for every heading
• decorative callouts
• a heading followed by a sentence that merely repeats it
• repeated "Key takeaway" boxes
• unnecessary conclusion sections

Use sentence case for headings unless the established style guide requires otherwise.

Formatting should make the information easier to find.

22. Keep politeness proportionate

Use enough courtesy to maintain the relationship. Stop there.

Avoid:

• "I hope this message finds you well."
• "Please do not hesitate to reach out."
• "I would be more than happy to..."
• "I was wondering if perhaps..."
• "Of course!"
• "Absolutely!"
• "Great question!"

One greeting and one "thanks" are usually enough.

Direct does not mean rude. State the request clearly and respect the reader's time.

23. Handle uncertainty honestly

State what is known, what is unknown, and what would resolve the uncertainty.

Good:

The logs show that the request failed after authentication. They do not show whether the upstream service timed out. We need the gateway logs to confirm that.

Do not fill gaps with plausible background, vague biography, or generic explanations.

Avoid stacked hedging:

It could potentially possibly be...

Use the narrowest accurate qualifier:

• may
• probably
• appears to
• the available evidence suggests

24. Describe the current state

Documentation and comments should usually explain how the system works now.

Weak:

This function was added to replace the previous implementation, which iterated through every item.

Better:

This function uses a hash map for constant-time lookups.

Narrate the change only in changelogs, release notes, migration guides, incident reports, or historical explanations.

25. End when the work is done

Do not add a generic conclusion after the necessary information.

Avoid:

• "In conclusion..."
• "The future looks bright."
• "This is a step in the right direction."
• "Exciting times lie ahead."
• "I hope this helps."
• "Let me know if you have any questions."

End with the result, the decision, the deadline, or the next action.

Editing process

Use this process internally unless the user asks to see the analysis.

First pass: meaning

Identify:

• the main point
• required facts
• decisions
• constraints
• uncertainties
• actions
• deadlines

Remove unsupported claims and invented details.

Second pass: structure

Move the main point to the beginning.

Group related information. Delete repetition. Merge weak paragraphs. Add headings only when they improve navigation.

Third pass: language

Replace:

• abstract nouns with verbs
• vague claims with specifics
• ceremonial language with direct language
• promotional wording with observable facts
• synonym cycling with stable terms

Fourth pass: rhetoric

Remove:

• slogans
• forced contrasts
• aphorisms
• rules of three
• artificial punchlines
• significance claims
• empty transitions
• fake-candid openers
• tutorial-style announcements

Fifth pass: rhythm and punctuation

Read the text aloud.

Check for:

• uniform sentence length
• repeated sentence patterns
• stacked fragments
• excessive parenthetical material
• em dashes
• dramatic punctuation
• paragraphs that end too neatly

Revise only where the rhythm interferes with clarity or sounds manufactured.

Final pass: reader test

Ask:

1. Can the reader identify the main point immediately?
2. Does each sentence add useful information?
3. Are actions, owners, and deadlines explicit?
4. Can any sentence be deleted without loss?
5. Does the tone fit the relationship and genre?
6. Is any phrase present mainly because it sounds polished?
7. Has the text preserved the author's actual voice?
8. Does the ending stop at the right place?

Return the final version. Do not expose drafts, audits, or self-critique unless requested.