Writing Clearly

Writing Clearly — простой и понятный текст

Core principle

Care for the reader. A text works when the reader understands it on first pass and gets something useful from it. Two rules, in this order:

1. Ясно — the reader must understand. Clarity comes first.
2. Коротко — every word must earn its place. Brevity serves clarity, never replaces it.

Cutting words is not the goal. «Коротко — не значит ясно»: throw out the trash, but ADD tools of clarity — examples, concrete details, structure. A long clear text beats a short murky one.

When to use

Any prose a human will read: docs, README, PR descriptions, reports, letters, posts, release notes, error messages, UI text, explanations, chat answers — Russian or English.

When NOT to use: source code and identifiers, literary fiction, legal text where exact boilerplate is required, texts where the user explicitly asks for a different style (academic, SEO, poetic) — the user's explicit request always wins.

Workflow

Step 0 — Reader and context (before writing a single word)

From «Ясно, понятно»: a text fails most often not because of bad sentences, but because the author ignored the reader. Answer briefly (to yourself, don't output):

• Who reads this? What do they already know? What terms are familiar to them?
• Where do they meet the text? Chat, README on GitHub, email, commit log, error dialog.
• What should they get? An action to take, a decision to make, an understanding to gain.
• What's their likely objection or prejudice? Address it, don't ignore it.

Then pick the register: professional for docs, neutral for posts, conversational for chat. Formality never excuses murkiness — even a formal text must be clear on first read. Details and register scale: references/yasno-ponyatno.md.

Step 1 — Structure (подача)

• Main idea first. In the text, in every section, in every paragraph. A reader who stops at any paragraph still leaves with the point.
• Informative headers. A header states the topic and the benefit, not a teaser. Test: if the header fits any other text on the topic, it's bad. «Преимущества» → «Экономия 40% на отоплении». "Overview" → "What the tool does and when to use it".
• One thought — one paragraph (3–5 sentences). Longer means two thoughts got mixed; split.
• Diagonal reading test. Read only the headers and first sentences of paragraphs: the skeleton of the argument must be visible.
• Every abstraction gets an example. Ideally an example AND a counterexample. If you state a rule, show it applied.

Step 2 — Editing (инфостиль)

Write, then pass through the text with these operations. Russian specifics and full tables: references/infostyle-ru.md. English: references/plain-english.md.

1. Stop words out — вводный мусор («стоит отметить», «как известно»), паразиты времени («на сегодняшний день»), hedging, filler. Delete; meaning survives.
2. Evaluations → facts — «качественный», «эффективный», "robust", "powerful": replace with the fact behind them («экономит 20% времени», "handles 10K rps") or delete.
3. Nominalizations → verbs — «осуществление поддержки» → «поддерживаем»; "perform validation" → "validate".
4. Passive → active, strong actor — «было принято решение» → «мы решили»; "the file is processed by the script" → "the script processes the file".
5. Bureaucratese and pretentious words → plain words — «данный» → «этот», «является» → тире, «имплементация» → «внедрение»; "utilize" → "use", "leverage" → "use".
6. Euphemisms → direct statements — «определённые сложности» → «серьёзные проблемы»; "suboptimal results" → "it failed". The reader must see there IS a problem.
7. Unfounded claims out — «всё больше людей», «стремительно набирает популярность», "many developers believe": cite data or delete. Substitution test: if any subject fits the sentence, the sentence says nothing.
8. Close synonyms → the strongest one — «долгого, нудного и утомительного» → «нудного», or better a fact: «два месяца». Beware the rule-of-three reflex.
9. One thought per sentence; simplify syntax — break split constructions («не только… но и…» with long parts), participle chains, «который» nesting.
10. Typography (Russian text) — «ёлочки», тире —/–, буква «ё», list punctuation.

Step 3 — Self-check (before returning the text)

Reread as a reader who never saw the draft:

• Main idea in the first paragraph? In each section's first sentence?
• Headers informative — would survive being read alone?
• Every abstraction has a concrete example?
• Any evaluation without proof left? Any unfounded claim?
• Any «данный/является/осуществляется» (RU) or "utilize/leverage/delve" (EN)?
• Passive where active would work?
• Read aloud (inner voice): stumble → rewrite; out of breath → sentence too long.
• Would you say this sentence to a colleague over coffee? If not — simplify.
• Meaning preserved? Nothing added that wasn't there? Not over-edited?

If the text was mostly good, minimal edits are the right answer. Quality, not edit count.

Quick reference — top offenders

Text-type adjustments

• Technical docs / README — keep established terms (API, деплой, backend) even if «заумные»; kill bureaucratese around them. Precision over casualness.
• PR / commit descriptions — what changed and why, main change first; facts, no «улучшена стабильность» without saying what exactly.
• Business letters / internal comms — euphemisms die first: the reader must understand the real situation. Ask or state directly, politely.
• Posts / announcements — personality allowed, first person welcome; rhythm varies; no corporate stamps («команда профессионалов»).
• UI text / errors — shortest register: what happened + what to do next.
• Chat answers — lead with the answer, then the reasoning.

Reference files

Common mistakes

• Over-editing: stripping the author's voice along with the trash. Preserve meaning and intent; do not add facts that weren't there.
• Brevity worship: cutting the example that made the text clear. Clarity first.
• Simplifying terms for experts: «оптимизация» is fine in an SEO text; the reader scale decides, not the word list.
• Sameness: all sentences the same length reads robotic. Vary short and long.
• Announcing instead of saying: «Рассмотрим следующий вопрос…» — just say the thing.