# Writing Clearly

> Use when writing or editing ANY prose for humans, in Russian or English — documentation, README, commit and PR descriptions, reports, business letters, posts, announcements, release notes, error messages, UI text, explanations, summaries, chat answers. Триггеры — «напиши текст/пост/письмо/статью/README/доку», «отредактируй», «упрости», «сократи», «объясни просто», «сделай понятнее», «инфостиль», «по Ильяхову»; and English "write", "rewrite", "simplify", "explain", "edit this text", "make it clearer". Apply even when the user asks for prose without naming a style — clear writing is the default. Based on Maxim Ilyakhov's «Пиши, сокращай» and «Ясно, понятно» — clarity first, then brevity. NOT for source code, identifiers, commit subjects under 50 chars, or literary fiction.

- Skill: `fockus/writing-clearly` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add fockus/writing-clearly`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fockus/writing-clearly/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: fockus (https://skillmd.com/u/fockus)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fockus/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

| Плохо (RU) | Хорошо | Bad (EN) | Good |
|---|---|---|---|
| данный | этот | utilize | use |
| является | — (тире) / это | leverage | use |
| осуществляет продажу | продаёт | perform an analysis | analyze |
| в настоящее время | сейчас | at this point in time | now |
| в целях | чтобы | in order to | to |
| было принято решение | мы решили | it was decided | we decided |
| определённые сложности | серьёзные проблемы | certain challenges | serious problems |
| стоит отметить, что | (удалить) | it is worth noting that | (delete) |
| широкий спектр | (перечислить) | a wide range of | (list them) |
| в рамках проекта | в проекте | within the framework of | in |

## 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

| File | When to load |
|---|---|
| `references/infostyle-ru.md` | Editing or writing Russian text — full stop-word, канцелярит, заумь, эвфемизм tables + typography + AI-marker checklist |
| `references/yasno-ponyatno.md` | Writing from scratch, structuring a long text, choosing register, reader analysis |
| `references/plain-english.md` | Writing or editing English text |
| `references/examples.md` | Before/after pairs by text type — load when unsure how far to edit |

## 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.