Skip to content

docs: Large editorial pass — terminology, formatting, markup#198

Draft
valeria-brazhnikova wants to merge 10 commits into
mainfrom
doc-updates-ddp
Draft

docs: Large editorial pass — terminology, formatting, markup#198
valeria-brazhnikova wants to merge 10 commits into
mainfrom
doc-updates-ddp

Conversation

@valeria-brazhnikova
Copy link
Copy Markdown
Contributor

Include edits from #196

Summary

Large documentation pass following an editorial review: alignment with the project style guide and glossary, unified table and list formatting, removal of excessive bold emphasis, and meaningful link anchors.

48 files changed, ~1.8k lines of changes.

What was done

1. Terminology and consistency

  • On first mention in each document, the abbreviation is expanded: DDPDeckhouse Development Platform (DDP).
  • Term spellings unified per the glossary: неймспейс, веб-интерфейс, IP-адрес, файлы cookie, etc.
  • Unused fields moduleStatus and d8Edition removed from front matter.
  • Product and component names normalized to canonical forms (Deckhouse Kubernetes Platform, Kafka, PostgreSQL).

2. Yo-fication (её)

Bulk replacement in common forms: учётные, создаётся, за счёт, путём, обновлённой, вернёт, найдёте, etc. Legal text and Residual risk sections were not touched.

3. Punctuation and typos

  • и т.д. / и т.п.и т. д. / и т. п.
  • Em-dash for definitions in lists and inline explanations.
  • Typos fixed: СихронизацияСинхронизация, кажогокаждого, при при, платформане подставляетплатформа не подставляет, etc.
  • Trailing periods removed from short table cells; periods between sentences in multi-sentence cells preserved.

4. Structural fixes

  • All numbered lists normalized to 1. 1. 1. (Markdown auto-numbering).
  • > ... blockquotes converted to Hugo {{< alert >}} shortcodes where applicable.
  • HTTP security headers (Content-Security-Policy, X-Frame-Options, etc.) wrapped in ` `.

5. Tables

  • Required/Optional columns unified to Да / Нет / Обязательно.
  • Bold removed from Да / Нет / Обязательно after spec clarification.
  • Capitalization applied in narrative table cells (e.g., опциональноОпционально); technical literals and identifiers left as-is.

6. Cleanup of **bold emphasis**

~1000 cases of excessive bold emphasis processed by rule:

  • Random prose emphasis — unbolded.
  • Parameter names, method names, identifiers, HTTP headers → `inline code`.
  • UI element names (widgets, buttons, form fields, sections) → «chevrons» in RU and "quotes" in EN.
  • Product/technology names (Kubernetes, GitLab, PostgreSQL, Dex, ...) — bold removed without replacement.
  • Broken markup fixed in admin/actions/types.ru.md, where ** incorrectly wrapped inline code.

7. Meaningful link anchors

Following the pattern of release-notes/v1.4.0.ru.md and v1.5.0.ru.md:

  • All [подробнее], [документация], [документе], [здесь], [см.], [См.] replaced with descriptive anchors — widget/action/section name or a key phrase (68 fixes across 10 files).
  • In the GitlabProjects parameters table (admin/datasources/types.ru.md), the "Возможные значения" and "По умолчанию" columns now contain concrete values instead of duplicate links.

Affected areas

  • admin/ — actions, architecture, datasources, examples, external-services, healthchecks, processes, security, widgets;
  • user/ — ai-assistant, catalog, credentials, interface, mcp-server, properties, teams-users, templating;
  • product-info/ — functional, licensing, lifecycle, staff, tech-support;
  • release-notes/ — v1.0.0–v1.4.0.

Verification

  • make lint-markdown — clean.
  • No content changes: only style, formatting, orthography, and anchors.
  • Legal wording and Residual risk sections were not touched (except for yo-fication).
  • _index.md / _index.ru.md were intentionally left unchanged.

Checklist

  • make lint-markdown passes
  • EN/RU parallel pages are consistent
  • No new English pages introduced
  • Terminology and anchors aligned with the style guide

maxinsky and others added 10 commits May 14, 2026 12:50
Signed-off-by: Max Chervov <max.chervov@gmail.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>
@MargaretKozlova MargaretKozlova requested a review from Lada7878 May 15, 2026 15:15
#### Обновление учётных данных пользователя

Если включена опция **обновление учётных данных пользователя**, то действие автоматически обновляет учётные данные пользователя в соответствии с правилами обновления.
Если включена опция обновление учётных данных пользователя, то действие автоматически обновляет учётные данные пользователя в соответствии с правилами обновления.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Это название в интерфейсе, надо как-то его выделять, или писать "опция обновления учетных данных пользователя"

##### Выбор пользователя для обновления учётных данных

По умолчанию учётные данные обновляются для пользователя, который запустил действие (инициатора). Чтобы обновить учётные данные другого пользователя, включите опцию **обновлять учётные данные конкретного пользователя** и выберите нужного пользователя.
По умолчанию учётные данные обновляются для пользователя, который запустил действие (инициатора). Чтобы обновить учётные данные другого пользователя, включите опцию обновлять учётные данные конкретного пользователя и выберите нужного пользователя.
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"обновлять учётные данные конкретного пользователя" - это название заголовка в интерфейсе, надо как-то его выделять

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants