Setting the file. One moment.
Subchapter 11.2
references/editorial-standards.mdMarkdown8 KBView on GitHub
Apply these standards to the passage and its surrounding section. They are editing criteria, not proof of authorship. A word or punctuation mark does not establish that text was generated by AI.
Every sentence should contribute a fact, relationship, qualification, example, or action the reader needs. Remove duplication without removing the distinctions that make the answer useful. Do not replace a detailed explanation with a broad claim that forces readers to infer the mechanism.
Check the latest accepted wording before editing. Preserve the intended audience and breadth of the title. A narrow example must not quietly redefine the page’s subject.
Read for progression: what does the reader know at the start of this paragraph, what do they learn, and why does the next paragraph follow? Use a transition when it expresses a real relationship. “Because,” “after,” “but,” and “for example” are useful when their meanings fit. A stock introduction does not create continuity.
Avoid these words in newly written promotional or explanatory prose: delve, foster, leverage, utilize, facilitate, empower, streamline, robust, cutting-edge, paradigm shift, game changer, tapestry, realm, beacon, multifaceted, meticulous, intricate, paramount, transformative, elevate, embark, supercharge, harness, and ever-evolving. Check inflected forms too.
Also remove unsupported ease or quality claims such as “easy,” “quick,” “simple,” “seamless,” “innovative,” and “comprehensive.” Replace the claim with what the reader does or what the system provides. Do not replace “robust” with an equally unsupported “reliable.”
Remove empty intensifiers and adverbs, including “just,” “very,” “basically,” “obviously,” “literally,” “honestly,” “actually,” “truly,” “fundamentally,” “importantly,” “crucially,” “inherently,” and “inevitably,” when they add no meaning. Preserve a qualifier that communicates real scope or uncertainty. “Statistically significant” is a technical claim that needs evidence, not an interchangeable version of “large.”
Delete filler such as “it’s worth noting,” “at the end of the day,” “when it comes to,” “at its core,” “in today’s world,” “the reality is,” “the truth is,” “going forward,” and “let’s dive in.” Replace “in order to” with “to.” Do not replace one filler phrase with another.
Preserve exact names, code tokens, error messages, and necessary quotations even when they contain a flagged word. Prefer paraphrasing unnecessary quotations. Never alter an exact quote silently.
| Pattern | What to check | Revision approach |
|---|---|---|
| Negation-and-reveal | “This isn’t X. It’s Y” or “not just X, but Y” delays the point | State the behavior directly; retain negation for a real limitation or distinction |
| Throat-clearing | “Here’s the thing” or “Let me be clear” delays the information | Start with the information |
| Faux insight | “What nobody tells you” claims special authority | Explain the overlooked mechanism with evidence |
| Dramatic reveal | A colon or self-answered question stages the answer | State the answer, reserving colons for functional uses |
| Negative listing | “Not X. Not Y. Z” builds through fragments | Explain Z and any necessary boundary together |
| Superficial analysis | A trailing “highlighting” or “underscoring” clause claims significance | Name the actual consequence or remove it |
| Importance claims | “Plays a vital role” tells readers what to value | Describe the role and its effect |
| Interpretive commentary | “This distinction matters” comments on the writing | Explain what changes for the reader |
| Vague authority | “Experts agree” or “studies show” lacks a source | Name and link the source or remove the claim |
| Inflated verbs | “Serves as a centralized hub” obscures an ordinary action | Use the exact action, such as “stores” or “routes” |
| Synonym cycling | One component becomes a tool, platform, and system | Keep one term unless the distinction is real |
| False ranges | “From X to Y” implies a scale that does not exist | Name the relevant items directly |
| Decorative ending | An aphorism restates the paragraph | End on the useful fact or action |
Do not substitute vague technical metaphors for mechanisms. Words such as “substrate,” “nexus,” “flywheel,” and “north star” often hide a simpler point. Keep precise domain terms when needed: a mathematical vector, API reference, or compiler primitive should not be renamed merely because the word appears in a style list.
Repeated sentence shape can survive a word-level rewrite. A run of “claim, qualification” sentences remains repetitive when “while” becomes “including” or “but.” Identify each sentence’s job and regroup ideas where the meaning supports it. Avoid adding filler to manufacture variation.
Do not split a connected explanation into a series of abrupt assertions. Conversely, split a dense sentence when its dependencies make readers backtrack. Neither short nor long sentences are inherently better.
Use the natural number of examples or constraints. Repeated three-part lists can become a default cadence. Preserve a genuine three-part model, but do not invent a third item for balance.
Watch for repeated antithesis across sections. Necessary limitations should stay explicit, but a section need not repeat “It is not” in every sentence. Prefer zero rhetorical contrast frames; retain a deliberate comparison when it improves understanding.
Avoid repeating an explanation across pages when a link to the canonical reference would serve the reader. Retain context needed to follow the current procedure, and keep exact technical terms consistent across guides and references.
Remove coverage announcements such as “This guide covers X, Y, and Z” when headings already provide that navigation. Preserve functional orientation in a complex procedure when the reader needs it to proceed.
Do not add opinions, first-person anecdotes, deliberate mistakes, or conversational mess to make documentation sound human. Voice comes from relevant detail, editorial judgment, and clear explanations. First person belongs where the author or team’s actual experience is relevant and supported.
These examples illustrate editorial reasoning, not current product behavior.
Original: “The validator is robust and ensures seamless releases.”
Revision, if supported: “The validator rejects a release when the configuration omits a required field.”
The revision names an observable behavior. It is appropriate only if that behavior has been verified.
Original: “Create a project. Add a domain. Deploy the changes.”
In an overview: “After creating a project and adding a domain, deploy the changes.”
In a procedure, retain separate numbered steps and supply each step’s necessary details. The same sequence needs different treatment depending on its purpose.
Original: “Requests may fail when the upstream service exceeds the timeout.”
Retain “may” if the outcome depends on retry behavior or another condition. Removing a hedge is a regression when it changes the claim.