On Writing Well (With LLMs)

Clear thinking becomes clear writing; one can’t exist without the other.

- William Zinsser, On Writing Well

Writing has always been vitally important, but never more so than now.

Good writing is good thinking. The act of writing down an idea forces you to clean it up, scrutinize it, and sharpen it.

Writing is also the most essential conduit for ideas within a company. Clear writing allows ideas to flow freely and without confusion, allowing the organization to tackle more complex challenges. But in a company that writes poorly — or doesn’t write at all — ideas flow slowly and ambiguously, leading to confusion and misalignment.

LLMs have made good writing more important than ever before, because prose has become the main way we interact with computers. Increasingly, we no longer write computer code or click buttons in a GUI; instead we tell the computer we want in English. The quality of the output we get is directly tied to the quality of the writing we put in.

For no profession is this more true than software engineering. Most programmers no longer write or read much code directly. Instead, we reason about the code through written English. This is a radical change to our job, and it means we must learn not only to write code well, but to write about code well.

In this document I’ll outline some guidelines for doing just that. These guidelines are meant for both humans and agents. Whenever an agent is writing on your behalf — whether a PR description, issue description, wiki article, public document, or product spec — you should show it this document.

When to Delegate (and Not)

However, before we dive in, a word of caution: be careful about what writing you delegate to an agent. Some forms of writing are appropriate to delegate to an agent, but others aren’t.

The key is to never outsource your thinking to an LLM. In many cases, the very purpose of writing is to force the author to think deeply about the problem at hand. The act of writing requires the writer to organize ideas in her mind, identify the gaps and errors in her thinking, and make her idea more coherent and elegant.

In these cases, using an LLM to do the writing is a bit like using an e-scooter on a treadmill. The whole point of the treadmill is to make you sweat, just as the point of writing is to exercise your mind. 

Here are some examples of writing that you should not delegate to an LLM:

• Product Specs: The act of defining how a product should work is too important to delegate to an LLM. Writing product specs forces you to empathize with your user and think through their experience step by step. The very act of doing this can reveal flaws in your original premise and identify crucial open questions that the team must resolve before moving forward. But neither of those things happens if you delegate the thinking to AI. 

• Original Public Docs: Writing public documentation is an extremely valuable exercise; it forces us to explain our product to our customers, which requires holding up a mirror to our product and asking whether it is intuitive, whether it solves a real problem, and whether it maps onto the customer’s way of thinking about things. 

• “Vision” Docs: If you’re asking an LLM to tell you what the vision of the product, company, or brand should be, then you are very lost.

LLMs can still be helpful assistants for these important documents. They can perform research, proofread your work, or play devil’s advocate. But the thinking must be yours, and the prose should be too.

However, there are plenty of other types of writing that are perfectly fine to delegate to an LLM. A rule of thumb here is that any writing that simply rephrases or reorganizes existing information is a great thing to outsource to an LLM. 

Here are some examples:

• Linear Issues: Creating Linear issues from Slack threads (or agentic coding threads) is a great use case for AI. Typically all of the relevant context is already sitting inside the thread, and the act of reshaping it into a coherent issue description is mostly a matter of rephrasing existing ideas, rather than generating new ones.

• Updating Wiki + Public Docs: While I would highly recommend writing the first draft of a public doc or wiki yourself, the task of updating them when features change can be rote, tedious, and not particularly enlightening. LLMs can and should help you here.

• PR Descriptions (Sometimes): PR descriptions can be tedious to write, and often the context needed to describe a PR already exists in 1) the chat thread with the coding agent and 2) the original issue description. So it’s usually fine to have an agent write the PR description, especially for straightforward PRs. But not always — sometimes for larger, more complex features it’s important to write aspects of these by hand, or at least to be very prescriptive about what the agent should write. 

• Commit Messages: Similarly commit messages are notoriously tedious to write, and most engineers historically do a terrible job at writing them. This is a great thing to outsource to a coding agent, because it already has extensive context about the change being made.

The common thread here is that these forms of writing are mostly mindless (though not always). They often involve regurgitating information you’ve already written down for a different audience or setting. In these cases, you aren’t delegating the important thinking to an LLM; typically you’ve already done the important thinking.

Guidelines

If you are going to have an LLM write for you, it’s important that they do it well. Without proper guidance, LLMs can be downright awful at writing. By default, they have a distinctive, instantly recognizable style that many readers rightfully find repugnant and painful to read.

The following guidelines are meant to help clean up AI-generated writing, but they are (mostly) relevant to humans as well, and I recommend all new employees read them at least once!

Be Concise

Rule #1 is to be concise. LLMs tend to be extremely long-winded. Typically their output is ~40% longer than it needs to be.

Follow William Zinsser’s advice: “Look for the clutter in your writing and prune it ruthlessly.” Delete any extra words or filler that aren’t adding anything, especially insipid Claude-isms like:

• “The honest read:...”

• “That’s something to sit with.”

• “Notice the arc of what just happened.”

Such phrases clutter the prose while adding zero additional information.

Another pro tip: even though it doesn’t reduce the total length, splitting up large paragraphs into smaller ones makes the text feel more concise and readable. “Walls of text” feel intimidating to human eyes — that \n character makes a big difference to us — but shorter paragraphs are easier to skim.

Lead With Why

Always begin by explaining why the reader should care in the first place. Don’t jump right into the details. It’s disorienting to the reader and you’re more likely to lose them.

Explain why this thing exists and why it deserves the reader’s attention. More specifically: 

• For public docs, explain what business problem the product feature helps the user solve.

• For internal wiki, explain why the system/feature exists in the first place and what it does for the user.

• For PR descriptions, explain why this change was made: what bug it was intended to solve, what customer request it satisfies, etc. (Without understanding the motivation, the reviewer has no way of determining whether the code he’s looking at solves the problem it was intended to solve.)

• For docstrings and inline comments, explain why the code exists and what problem it’s solving, especially if it’s not self-evident from the code itself.

Don’t overdo it here. You don’t have to turn every intro paragraph into a sales pitch. But I’ve seen far too much writing — from both LLMs and humans — that fails to answer upfront the question: “What is this and why should I care about it?”

Empathize with the Reader

Try hard to put yourself in the reader’s shoes. Ask yourself: Who is going to read this document? What do they care most about? What parts are likely to confuse them and deserve extra clarity? Conversely, which things are obvious and don’t need to be explained?

For example:

• A reader of our public docs is typically a marketer. They know a lot about marketing but very little about software engineering. They don’t care about how the system works under the hood; they care about how they can use it to get their job done.

• A reader of the wiki is a fellow engineer, but they could be senior or junior, new to the company or a veteran, front-end or back-end leaning. It’s safe to assume they understand our codebase at a basic level, but they might be utterly unfamiliar with your particular feature or system.

• A reader of a PR description is a fellow engineer who is probably somewhat familiar with this part of the codebase, so you can assume a high degree of background knowledge. But they are also very busy, and they might not remember the context around this particular change, so it’s important to remind them.

Don’t assume that the reader has the same context that you do. Assume he needs to be brought up to speed a bit.

A good heuristic here is the college roommate test. Pretend your reader is your intelligent college roommate who has a different major than you. They’re smart, so you don’t need to patronize them, but you also can’t assume they understand any of the jargon from your field, so it’s important to use plain language and to start by laying a foundation for what you’re about to explain.

Avoid Jargon

Even when your audience is other experienced software engineers, it’s best to avoid jargon and opt instead for plain, straightforward language. Here are some examples:

• "Suboptimal performance characteristics" → "This function is too slow"

• "The system exhibits non-deterministic behavior under load" → "The system sometimes fails when traffic is high"

• "This introduces additional operational complexity" → "This makes the system harder to run and maintain"

• "We should leverage the existing abstraction" → "We should reuse the existing component"

Especially bad is made up jargon. Recent Claude models have developed a bizarre habit of inventing jargon that sounds real but, as far as I can tell, is made up. Here are some examples we’ve encountered recently:

• “The machine contract”

• “Run an artifact probe”

• “Vacuity guard”

• “Validate the extraction kill-test”

It’s unclear if these terms are made up or just extremely obscure. In any case, they should be avoided at all costs.

Some jargon is okay. Once in a while, a term like “idempotent”, “network latency”, or “sublinear time complexity” is precisely what you need, and there is no simpler substitute. (“Idempotent” has no simpler synonym that I’m aware of; its meaning is extremely specific.)

But try to keep the jargon to a minimum. Remember, your goal is not to sound smart or impress the reader with all the fancy words you know. Your goal is to transmit ideas from your brain to someone else’s, and for that, plain language works best. 

Be Concrete, Use Examples

A lot of technical writing suffers from the same problem: it’s too abstract. Programmers (and LLMs) are taught to think in terms of abstractions; we always try to extrapolate a pattern, and we prefer general solutions over specific ones.

However, when it comes to prose, this impulse is often wrong, as it makes the writing much harder to follow. Therefore you should always try to be concrete in your writing, and the best way to do that is to use realistic examples. Try to follow every abstract statement with a specific example that helps the reader conceptualize how your statement applies in practice. Here’s an example.

Imagine you’re explaining different database technologies to your reader:

Whereas an OLTP database is designed for transactional workflows, e.g. reading, writing, and updating single rows, an OLAP database is designed for analytical workflows, such as aggregations across large datasets.

That’s not a bad sentence, but it's quite vague, and the reader might struggle to wrap their head around it. Following it up with a practical example can help the reader understand what it really means in practice:

Imagine you’re running an e-commerce store. An OLTP database would power most of the main screens on the website. For example, the product page would read a row from the products table. When a user adds an item to their cart, it might create a new record in the carts table. These operations work best in an OLTP database.

On the other hand, imagine you’re running some analysis on your business, and you want to compute aggregate metrics like the total revenue last quarter, the average number of items in a cart, or the total number of distinct customers. These queries require crunching numbers across many rows, so an OLAP database is the right tool for the job.

Now the reader has a clear picture of how abstract concepts from the first paragraph apply in practice. Suddenly the abstract concept doesn’t feel so abstract after all!

The more realistic the example the better. Realistic examples pertaining to real customers or real use cases are not only easier to understand, they also force you to consider whether your solution actually works in the real world. If you can’t think of a realistic example of your abstraction at work, that could be a sign that it’s a bad abstraction.

Avoid Obvious Claude-isms

There are a handful of tells that make it extremely obvious that writing is AI-generated. I’ll call these “Claude-isms” because Claude seems to be the worst offender, but many LLMs share these same bad habits. The most notorious is the em dash (“—”). 

The em dash is actually a perfectly respectable and useful piece of punctuation. I’m not saying you should never use it. But LLMs have a tendency to really overdo it. Their prose is absolutely littered with them. If you’re an LLM reading this, try showing some love to other grammatical constructions, such as:

• Parenthetical asides

• Semicolons

• Subordinate clauses

• Simply splitting long sentences into shorter ones

In addition to the infamous em dash, here is a list of other obvious Claude-isms that should be avoided.

Starting a sentence with an anticipatory colon:

• "That's the whole pitch:..."

• “The honest read:...”

• “The key distinction I care about:...”

These specific phrases:

• “Falls out of this”

• “Travels together”

• “Doing real work”

• “Load bearing”

• “Sit with that.”

• “Notice what just happened”

• “That sounds like a gotcha, but it’s not”

• “Here’s the thing”

• “I’ve been thinking about this a lot lately” (Really? Have you, Claude?)

Overuse of these words:

• “Honest”, “honestly”, “honestly?”

• “Real”

• “Genuinely”

The negation flip:

• “Not a blank page. A system.”

• “It’s not just X. It’s Y.”

• “It’s not a productivity problem. It’s a prioritization problem.”

The point in avoiding these obvious AI tells is not to fool the reader into thinking that the prose isn’t AI-generated. It’s okay to use AI for some writing, and we should be honest with the reader when we do.

The point is to show the reader respect — to assure them that the author at least took the time to audit the LLM’s output, tighten it up, add his own thoughts and ideas to it, rather than simply forcing the audience to read slop that they could’ve generated themselves anyway. 

In the past, software engineers often thought about writing as “work about work”: something separate from, and distracting from, the real work of writing code. But now more than ever, writing is the work. Written English is how code gets written, how code is understood, and how information and ideas flow throughout a company.

Because writing is thinking made visible, the quality of our writing will increasingly determine the quality of our work. So whether you’re writing it yourself, as you often should, or having AI write on your behalf, the art of writing has never been more important.