Good Writing

Good writing rules

Ported (translated + condensed) from the Russian-language good-writing skill in mikeshu2001/content-factory. The original is the source of truth for Russian-specific grammar rules; this port keeps every transferable rule in English. Attribution: mikeshu2001. The original files are not vendored verbatim because this repo is English-only on disk (docs/developing-ralphy.md).

How to use this skill

This is not a list of bans to tick off. It is a toolset for moments of doubt. The goal: text should explain the way a person explains to a colleague over coffee. Not like a manual, not like marketing, not like an academic paper.

Before editing anything, ask:

• What does this phrase carry for the reader? If nothing — delete it. If it duplicates what was already said — delete it.
• What role does a construction play before you remove it by rule? A formally "banned" construction often holds an important nuance. Understand why it is there first, then decide.
• Does the majority of readers need this fact? A detail useful to 5% of the audience that does not help the rest understand — cut.
• The main test after ANY edit: read the paragraph aloud and ask "would a native speaker say this to a colleague?" If not, the edit is bad even if it is rule-correct. Rewrite the sentence whole; do not patch one word.
• Symptom vs cause. Filler in one phrase usually means the whole paragraph is overloaded. Clean the paragraph, not the sentence. A "not X but Y" contrast usually means you have not found the affirmative form — find it.
• Judge the block, not the sentence. After any edit re-read the whole block. If the edit did not improve the block as a whole, it did not happen.

If a construction is allowed by the rules but sounds clumsy — rewrite it. If it is banned but sounds natural and precise — keep it. Rules are for doubt, not a final judge.

Tone

Calm, informational. No marketing, no exclamation, no attempts to impress. Talk WITH the reader, not AT them. Direct address is fine; chumminess is not. Be direct: if something does not work, say so plainly; if something matters, say it first, not after a wind-up.

Coherence

Every next sentence answers the question that arises after the previous one. The reader must never guess how two thoughts connect.

Connections must be semantic, not verbal. If one sentence logically continues another, do not add "because / therefore / also" — those words are only for places where the link is not obvious without them. Paragraphs must also continue each other; a paragraph change must not feel like a topic jump.

Progressive disclosure. A new concept appears only after the reader has developed a need for it. Do not open with "X is Y". First show the situation, limitation, or question that naturally leads to X — then the term is an answer, not a dictionary entry. After drafting, strip the headings and read the text as one flow: if the paragraph order is unclear without headings, the logic (not the headings) is broken.

Quantitative steps. Do not skip intermediate steps in a process. If a process has stages with counts ("one video = 5 scenes, one poster per scene"), state them explicitly and show how each stage's output feeds the next.

Paragraphs and sentences

Paragraphs are 2-4 sentences, one thought each. Exception: explaining a new concept or a process may take 4-6 sentences — do not shred it into fragments.

Sentences are complete, with a subject and a verb. Every sentence must move the thought forward: if you can delete it and the paragraph's meaning survives, delete it. One block = one job (explain, show an example, instruct, warn) — do not mix jobs inside a block.

Start with the point

No "In today's world..." style intros, no sentences that announce information is coming. If the block heading is "Why the tool fails", the reader knows why they are here — answer the heading immediately. Do not write transition paragraphs between blocks; the heading already gives context.