Unwritten content rules that experienced writers follow

This post is part of the Per the Docs article series. Links to the rest of the series are at the end of this piece.

• The Oxford comma is non-negotiable
• The Strangler Fig problem
• Sally in accounting
• "Unable" - I can't
• The -ing problem
• What happens when you work with AI

The Oxford comma is non-negotiable

Experienced writers follow style guides, and they know when to break the rules. It's a skill of its own to understand the intent behind the rules well enough to recognize when following them works against the reader.

For example, I'm currently required to apply the AP style guide in my work. The AP doesn't use the Oxford comma. But for technical content, I do... always.

The Oxford comma prevents ambiguity in lists, and ambiguity in technical documentation has consequences. "Scope includes admin, read and write access." Is that three scopes, or two, where read/write is a paired permission level? The same ambiguity appears in "The API removes the primary record, the secondary pointer and child objects." Are we talking about secondary pointers and secondary child objects, or secondary pointers and all children? In access control and data deletion, that's not a question you want readers to answer for themselves.

I follow the spirit of a style guide: consistency, clarity, and respect for the reader. When a specific rule works against those goals, I make a conscious decision to override it and I'm prepared to defend that decision.

The Strangler Fig problem

One of the trickiest judgment calls in technical writing is knowing when to use the right term versus the useful term. Subject matter experts often want documentation to reflect their vocabulary. But experienced writers know that doesn't always align with the reader's vocabulary.

I recently rewrote the deployment instructions for a software system. The internal team had described the migration approach as a "Strangler Fig pattern" and used that phrase in the first rev of the docs. It's a legitimate software architecture concept where a new system gradually replaces an old one by wrapping around it. The term is technically accurate and completely correct, but entirely wrong for the audience.

The people reading the deployment guide need to understand how the migration works, but introducing this pattern name requires readers to first learn what a strangler fig tree is, understand why that metaphor applies to software architecture, and then finally arrive at the concept itself. That's two layers of context the reader has to climb before they reach information they can use.

Directly describe the behavior to get them there in one step: the system transitions gradually, and existing functionality remains available while new components are introduced. Easy peasy.

Sally in accounting

Read the room. It's an essential skill that a writer needs to have, and one of the hardest to teach. It's the ability to sense who's in the audience and write accordingly.

When I wrote documentation for SugarCRM, I developed an imaginary user I called Sally in accounting. Sally is intelligent, capable, and completely non-technical. She uses the CRM every day to do her job and has zero interest in how it works under the hood. She just needs it to work.

Nobody told me to think about Sally. No brief mentioned her. But I knew she was in the audience, and she shaped every word I wrote. I'd ruthlessly eliminate jargon, lead with outcomes rather than mechanisms, and ask whether someone without technical context could successfully act on what I'd written.

As writers, we need to sense who's in the audience, even when nobody tells us explicitly.

"Unable" - I can't

Some tacit knowledge shows up as a persistent editor reflex. It's something you fix automatically across every draft you touch, without ever having formalized it as a rule.

The word "unable" is one of mine. It's passive, slightly formal, and creates distance between the reader and the action. "You are unable to proceed" becomes "you can't proceed." Just a tweak, but a massive difference in tone. I've never written this down as a rule, but I fix it every time.

The -ing problem

Two standard style guide rules operate together here:

If a task has a qualifier, lead with it. The goal or condition belongs at the beginning of the sentence, not the end. The reader needs context before instruction.

Use -ing words with care. A word that ends in -ing can be a verb, a noun, or an adjective, and this ambiguity creates risk. "By doing this, you can do that" breaks both rules at once. It buries the goal at the end and introduces an -ing word that could be read multiple ways. "To do that, try this" fixes both problems.

Both of these rules appear in the Google Developer Style Guide and the Microsoft Style Guide, but they're surprisingly overlooked by even experienced writers. I'm pedantic enough about these that I run a Ctrl+F for "ing" on every page I touch (don't do that on this blog post please - I'm referring to formal docs!). Gerund abuse and misplaced qualifiers tend to travel together. This thirty-second search is a standard part of my editing pass.

What happens when you work with AI

I've used AI tools heavily in my work for the past few years, and the collaboration has sharpened my understanding of tacit knowledge. AI will do what you ask. It follows the rules. Unlike humans, it's relentlessly consistent. This consistency means that it regularly produces output that a writer immediately knows is just plain wrong.

A few examples from my own workflow:

• I asked an AI to restructure an API reference for scannability. The result was technically well-organized. I rewrote it anyway, because the restructure had broken the logical progression a that developer needs to understand the underlying model before the reference makes sense.
• I asked an AI to clean up passive voice throughout a set of procedures. It did. I put some of it back, because active voice in certain warning contexts implies user agency where there isn't any. "This action can't be undone" is more accurate than "you can't undo this action" when the system is the one that enforces the constraint, not the user's decision.
• I reviewed microcopy for a deletion confirmation where AI-generated copy used the phrase "you can't recover this item." True, but recover is ambiguous. It could mean the item can't be restored after deletion, or it could mean the item can't be recreated at all. Those are very different things.

In each case, the fix came from my years of watching how people read, misread, and act on documentation.

LLMs are remarkably good at following explicit rules. Feed one your style guide and it will apply it more consistently than humans will. But tacit knowledge is different. It's knowing when a technically correct term will create unnecessary cognitive load, when a style guide rule works against clarity, who's reading and what they really need to know (and what they don't), and what's wrong with a sentence before you can articulate why.

The fact that a writer's knowledge resists codification is what makes it valuable. Style guides capture what can be taught. Experienced writers carry what can't. Our craft lives within this gap.

This post is part of Per the docs, a monthly collaborative series where technical writers explore different aspects of our craft. Each month features a new topic with perspectives from writers across the community. Read more perspectives in the series:

April 2026 topic: Mind the Gap

• Previous post: James Beach - Find it to Mind it: Taxonomies as Gap-Finders →
• Next post: Nicholas Galinski - Don't turn off your brain →

View all participants in this month's hop →

Disclaimer: Each article in this series is written and owned by its respective author. The views, opinions, and experiences shared belong solely to the individual writer and do not represent the perspectives of other participants or their employers (past or present).