docs: Large editorial pass — terminology, formatting, markup by valeria-brazhnikova · Pull Request #198 · deckhouse/website-development-platform

valeria-brazhnikova · 2026-05-15T14:45:48Z

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: DDP → Deckhouse 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

Signed-off-by: Max Chervov <max.chervov@gmail.com>

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

github-actions · 2026-05-19T11:51:08Z

✅ Deployment Succeeded

Environment: test

Access URLs:

🇬🇧 English
🇷🇺 Russian

Lada7878

Fix, please

Co-authored-by: Lada Lysenko <127337005+Lada7878@users.noreply.github.com> Co-authored-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>

github-actions · 2026-05-20T07:10:27Z

✅ Deployment Succeeded

Environment: test

Access URLs:

🇬🇧 English
🇷🇺 Russian

Lada7878 · 2026-05-20T07:07:43Z

-По умолчанию учётные данные обновляются для пользователя, который запустил действие (инициатора). Чтобы обновить учётные данные другого пользователя, включите опцию **обновлять учётные данные конкретного пользователя** и выберите нужного пользователя.
+По умолчанию учётные данные обновляются для пользователя, который запустил действие (инициатора).
+
+{{< alert level="info" >}}


Посмотри на тесте, может алерт и выделение вообще не нужны, в принципе, короткий абзац.

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Co-authored-by: Lada Lysenko <127337005+Lada7878@users.noreply.github.com> Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Co-authored-by: Lada Lysenko <127337005+Lada7878@users.noreply.github.com> Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

valeria-brazhnikova · 2026-05-20T14:09:21Z

 Для реализации автоматического обновления сервисов используются следующие компоненты Deckhouse Development Platform (DDP):

- Ресурс:
+- Ресурсы — это элементы модели данных каталога DDP, которые определяют структуру хранения информации. Каждый ресурс может содержать параметры для хранения метаданных сущностей, а также связи с другими ресурсами для отображения зависимостей.


У нас вот тут без кавычек всё

valeria-brazhnikova · 2026-05-20T14:11:15Z

    - автоматическое создание в сервисах, созданных из шаблона, Merge Request с изменениями из новой версии.

 ## Создание ресурсов и связи

-> **Ресурсы** — это элементы модели данных каталога DDP, которые определяют структуру хранения информации. Каждый ресурс может содержать параметры для хранения метаданных сущностей, а также связи с другими ресурсами для отображения зависимостей.
+«Ресурсы» — это элементы модели данных каталога DDP, которые определяют структуру хранения информации. Каждый ресурс может содержать параметры для хранения метаданных сущностей, а также связи с другими ресурсами для отображения зависимостей.


А тут в кавычках. Что делать будем?

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

maxinsky and others added 10 commits May 14, 2026 12:50

Edits

7af7877

Signed-off-by: Max Chervov <max.chervov@gmail.com>

Fix by promt /admin

dcad056

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fixes /product-info and /user by promt

2ce52ba

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Merge branch 'main' into doc-updates-ddp

e5a6529

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Merge fixes

d6b47d7

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Merge branch 'docs/review-about' into doc-updates-ddp

a01e6dc

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fixes of bold text

59fbe28

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fixes of bold text

a8c6b1d

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fixes of bold text

1d2e30a

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fixes of links

c84bd31

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

MargaretKozlova requested a review from Lada7878 May 15, 2026 15:15

Avtandilko approved these changes May 17, 2026

View reviewed changes

Comment thread content/documentation/admin/actions/overview.ru.md Outdated

Comment thread content/documentation/admin/actions/overview.ru.md Outdated

Lada7878 added the deploy/test label May 19, 2026

github-actions Bot removed the deploy/test label May 19, 2026

Lada7878 reviewed May 19, 2026

View reviewed changes

valeria-brazhnikova commented May 19, 2026

View reviewed changes

Comment thread content/documentation/admin/examples/service-autoupdates.ru.md Outdated

valeria-brazhnikova and others added 2 commits May 19, 2026 18:26

Apply suggestions from code review (Lada)

d9bed92

Co-authored-by: Lada Lysenko <127337005+Lada7878@users.noreply.github.com> Co-authored-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com> Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fixes after review

7f0ee21

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Lada7878 added the deploy/test label May 20, 2026

github-actions Bot removed the deploy/test label May 20, 2026

Lada7878 reviewed May 20, 2026

View reviewed changes

valeria-brazhnikova and others added 6 commits May 20, 2026 12:41

Fixes after review

d798c53

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Apply suggestions from code review

983470b

Co-authored-by: Lada Lysenko <127337005+Lada7878@users.noreply.github.com> Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fixes after review

69aed55

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Apply suggestions from code review

2bfa5e1

Co-authored-by: Lada Lysenko <127337005+Lada7878@users.noreply.github.com> Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fixes of alerts

15481e5

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

fix

28c6535

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Fix after rebase

e486c64

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

valeria-brazhnikova commented May 20, 2026

View reviewed changes

Merge branch 'main' into doc-updates-ddp

20ad0f7

Signed-off-by: Valeria Brazhnikova <valeria.brazhnikova@flant.com>

Conversation

valeria-brazhnikova commented May 15, 2026

Summary

What was done

1. Terminology and consistency

2. Yo-fication (е → ё)

3. Punctuation and typos

4. Structural fixes

5. Tables

6. Cleanup of **bold emphasis**

7. Meaningful link anchors

Affected areas

Verification

Checklist

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deployment Succeeded

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Lada7878 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions Bot commented May 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deployment Succeeded

Uh oh!

Uh oh!

Lada7878 May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

valeria-brazhnikova May 20, 2026

Choose a reason for hiding this comment

Uh oh!

valeria-brazhnikova May 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

2. Yo-fication (`е` → `ё`)

6. Cleanup of `bold emphasis`

github-actions Bot commented May 19, 2026 •

edited

Loading

github-actions Bot commented May 20, 2026 •

edited

Loading