# Technical Writing Rules — AI Reference
# Auto-generated from tw-styleguide.md, tw-glossary.md, tw-structure.md
# Do not edit manually — run generate_llm_files.py to regenerate.

---

## Style Guide

Этот стайлгайд описывает рекомендации по написанию технической документации для продуктов компании «Флант» на русском языке.
Документ предназначен для технических писателей и всех сотрудников, которые пишут документацию, ориентированную на клиентов компании.

## Общие рекомендации

### Доступность

- Разбивайте сплошные блоки текста, чтобы читателям было легче пробегать его глазами.
  Для этого дробите текст на абзацы, используйте заголовки и списки.

- Разбивайте длинные предложения на короткие — их легче читать.
  Чтобы ритм текста был естественным, чередуйте короткие предложения с более длинными.

- Главную мысль абзаца размещайте в первом предложении.

### Язык и стиль

- Старайтесь писать кратко и ясно в нейтральном тоне.
  Не используйте восклицательный знак.
  Вопросительный знак уместен только в заголовках раздела FAQ.

- В текстах инструкций используйте повелительное наклонение и обращайтесь к читателю на «вы».
  Не злоупотребляйте местоимениями «вам» и «ваши».

- Не упоминайте себя и нас в документации.
  Исключение — вводное слово «предположим» в примерах.

- Не используйте слово «пожалуйста» в документации.
  Это не признак грубости — мы просто не хотим вставлять это слово во все этапы всех инструкций.

- Избегайте прикладных англицизмов и жаргона, за исключением слов в [«Глоссарии»](tw-glossary.md).
  Читатели могут не знать узкоспециальной терминологии.

- Расшифровывайте сокращения и аббревиатуры при их первом появлении на странице.
  При расшифровке укажите полную форму и рядом в скобках аббревиатуру, которая будет использоваться далее по тексту.

- Используйте букву «ё».

## Оформление текста

### Заголовки

- Используйте в документации заголовки уровней H2–H4.
  Заголовок H1 в пределах одной страницы должен быть только один.
  Как правило, он указывается в поле `title` в блоке метаданных.

- По возможности не используйте заголовки уровня H5 и ниже.
  Пересмотрите структуру — возможно, имеет смысл выделить часть документа на отдельную страницу.
  Если это невозможно, используйте полужирное начертание вместо заголовков H5.
  
- Если на заголовок, созданный с помощью полужирного начертания, нужно ссылаться из других частей документации,
  добавьте к нему якорь с помощью конструкции `.anchored`.
  После этого на него можно будет ссылаться как на обычный заголовок.

- В заголовках кратко формулируйте суть подраздела. Избегайте длинных заголовков.

- Не используйте точки и восклицательные знаки в конце заголовков.
  Вопросительные знаки допустимы только в конце заголовков раздела FAQ.

- По возможности избегайте заголовков из нескольких предложений.
  Если одного предложения недостаточно, разделяйте предложения точкой, но не ставьте точку в конце последнего предложения.

- Не используйте бэктики в заголовках — даже в случаях, когда они требуются по другим правилам стайлгайда (например, для названий модулей или параметров).

### Списки

- Используйте списки для перечисления трёх и более элементов.
  Если элементов меньше трёх, оформляйте их в виде обычного предложения.

- Если список состоит из нескольких уровней или содержит повторяющиеся элементы, по возможности замените его таблицей.

- Всегда добавляйте вводную фразу перед списком и отделяйте ее от первого пункта пустой строкой.

- По возможности начинайте все пункты списка одинаково.
  Например, с глагола в одной форме.

- Если пункт списка в Markdown содержит несколько абзацев, отбивайте их пустой строкой и сохраняйте отступы слева,
  чтобы список не разваливался: три пробела для нумерованного списка и два — для маркированного.

#### Маркированные списки

- Используйте маркированные списки, когда порядок пунктов не важен.
  Например, при перечислении характеристик или равнозначных вариантов.

- Если пункты списка продолжают вводное предложение, пишите их со строчной буквы и заканчивайте точкой с запятой.
  В конце последнего пункта ставьте точку.

- Если каждый пункт списка — это отдельное предложение, начинайте его с заглавной буквы и ставьте точку в конце.

#### Нумерованные списки

- Используйте нумерованные списки, когда важен порядок пунктов.
  Например, в пошаговых инструкциях или когда нужно зафиксировать последовательность действий.

- Оформляйте каждый пункт списка как отдельное предложение. В конце каждого пункта ставьте точку.

- В нумерованных списках в Markdown по возможности используйте `1.` для всех пунктов.
  В отрендеренной документации такой список будет пронумерован как обычно.
  Это удобно, чтобы не запутаться в номерах пунктов при редактировании списка.

### Ссылки

- Формулируйте текст ссылки так, чтобы было понятно, куда она ведёт.
  Не используйте слова «здесь», «тут», «по ссылке» и подобные.

- Включайте в текст ссылки предлоги и зависимые слова.

- По возможности не включайте в текст ссылки более пяти слов.

- Оформляйте ссылки в Markdown следующим образом:

    - Ссылки в документации продукта (DKP, DVP, DDP и другие):

        - Если ссылка ведёт на один из подзаголовков на той же странице, укажите ее в формате `#заголовок`.

        - Если ссылка ведёт на другую страницу документации в пределах того же продукта, используйте относительный путь (например, `../..`).
          Чтобы не вычислять вручную, на сколько уровней вверх нужно прыгнуть, используйте [утилиту `truc`](https://github.com/Zhbert/truc).

        - Если ссылка ведёт на документацию другого продукта, используйте абсолютный путь вида `/products/<название-продукта>/documentation/`.

        - Если ссылка ведёт на документацию одного из модулей, используйте абсолютный путь вида `/modules/<название-модуля>/`.

    - Ссылки в документации модуля (внешнего или внутреннего):

        - Если ссылка ведёт на один из подзаголовков на той же странице, укажите ее в формате `#заголовок`.

        - Если ссылка ведёт на другую страницу документации в пределах того же модуля, используйте относительный путь (например, `../..`).
          Чтобы не вычислять вручную, на сколько уровней вверх нужно прыгнуть, используйте [утилиту `truc`](https://github.com/Zhbert/truc).

        - Если ссылка ведёт на документацию другого модуля, используйте абсолютный путь вида `/modules/<название-модуля>/`.

        - Если ссылка ведёт на документацию одного из продуктов (DKP, DVP, DDP и другие), используйте абсолютный путь вида `/products/<название-продукта>/documentation/`.

- При упоминании кастомного ресурса или его параметра по возможности добавляйте ссылку на соответствующее описание.
  При этом не стоит повторять одну и ту же ссылку в пределах того же абзаца или соседних предложений, если читателю уже понятно, о каком ресурсе или параметре идёт речь.

### Бэктики

- Выделяйте бэктиками:

    - названия модулей (`node-manager`);
    - названия параметров (`instanceTypes.rootDisk`);
    - значения параметров (`true`);
    - названия состояний и статусов (`Ready`, `Completed`, `Running`);
    - названия CLI-утилит (`kubectl`, `d8`);
    - имена объектов Kubernetes (ModuleConfig `deckhouse`);
    - пути к файлам (скрипт `/var/lib/bashible/cleanup_static_node.sh`);
    - номера сетевых портов (`2379`);
    - короткие команды (`d8 k`, `dhctl converge`);
    - коды HTTP-ответов (`200 OK`);
    - значения, которые пользователь должен набрать на клавиатуре (в качестве имени пользователя введите `license-token`);
    - HTTP-заголовки (`Content-Security-Policy`);
    - эндпоинты (`POST /token`).

- Не выделяйте бэктиками названия типов ресурсов Kubernetes (ModuleConfig, ClusterConfiguration, NodeGroup).

- Не используйте бэктики в заголовках.

### Блоки кода

- Используйте блоки кода для длинных команд, которые пользователю будет удобнее скопировать из документации, чем набирать вручную.

- После открывающих тройных бэктиков указывайте язык или формат кода для корректной подсветки в документации.
  Используйте `shell` или `bash` для консольных команд.
  Если блок содержит вывод команды, используйте `console` или `text` — даже если в выводе присутствует YAML или JSON.

- По возможности разбивайте длинные команды на строки для лучшего восприятия.

- Комментарии в коде оформляйте как обычные предложения: с заглавной буквы и с точкой в конце.
  По возможности размещайте комментарий на отдельной строке перед элементом, к которому он относится.
  Так его проще читать, особенно в YAML и других форматах со вложенной структурой.

### Предупреждения (алерты или callouts)

- Используйте блоки предупреждений, чтобы обратить внимание читателя на важную информацию.

- Пишите текст предупреждений кратко. Если предупреждение разрастается до нескольких предложений или включает списки, команды и другие элементы, будет лучше сделать его частью основного текста.

- Используйте один из трех уровней критичности:
  
    - `info` — дополнительная информация;
    - `warning` — возможные проблемы или ограничения;
    - `danger` — критические ситуации, которые могут привести к ошибкам или потере данных.

- Не используйте больше двух предупреждений подряд — есть риск, что читатель их пропустит.
  Вместо этого попробуйте объединить их в одно предупреждение в виде списка, если это допустимо по смыслу и они совпадают по уровню критичности.
  Либо вынесите их в новый подраздел «Обратите внимание» или «Перед началом работы».

- Для предупреждений в документации продуктов (DKP, DVP, DDP, Stronghold) и встроенных модулей
  используйте формат `{% alert level="<критичность-предупреждения>" %}...{% endalert %}`.

- Для предупреждений в документации внешних модулей
  используйте формат `{{< alert level="критичность-предупреждения" >}}...{{< /alert >}}`.

- Предупреждения в описаниях параметров модулей и кастомных ресурсов оформляйте в виде цитаты.
  Для уровней `warning` или `danger` используйте слово «внимание» с точкой на конце.

### Числительные

- Числительные от одного до десяти пишите словами или цифрами.
  Числительные больше десяти пишите только цифрами.

- В формулах, параметрах и значениях настроек используйте только цифры.

- Для разделения разрядов, начиная с пятизначных числительных, используйте неразрывные пробелы.

- Используйте буквенное окончание только для порядковых числительных.

- Не используйте буквенное окончание для количественных числительных.

- Если предпоследняя буква числительного — гласная, используйте однобуквенное окончание.

- Если предпоследняя буква — согласная, используйте двухбуквенное окончание:

### Единицы измерения

- Используйте русскоязычные сокращения единиц измерения.

### Знаки препинания и спецсимволы

#### Кавычки

- В тексте документации используйте только кавычки-ёлочки (`« »`).

- Используйте кавычки в названиях разделов документации.

- Используйте кавычки в названиях элементов интерфейса (раздела, вкладки, кнопки и других).

- Заключайте в кавычки русскоязычные названия компаний и продуктов. Англоязычные пишите без кавычек.

#### Тире и дефис

- Используйте длинное тире (`—`, em dash) между словами.
  Не используйте двойной дефис или короткое тире в этом случае.

- Используйте короткое тире (`–`, en dash) в числовых диапазонах, без пробелов:

- Используйте дефис (`-`, hyphen) в составных словах.

#### Спецсимволы

- Используйте символьную стрелку (`→`) при описании навигации в веб-интерфейсе.
  Не используйте сочетание дефиса и знака «больше» (`->`) для этого.

### Выделение текста

- Используйте `**полужирное начертание**`, чтобы выделить ключевую мысль в начале абзаца или в начале пунктов списка.
  Не злоупотребляйте этим способом выделения.
  Если полужирным выделен большой фрагмент текста, читателю становится сложнее понять, что именно важно.

- Используйте `_курсив_` для ввода нового понятия или интонационного акцента. Не злоупотребляйте курсивом.

### Оформление в Markdown

- По возможности разбивайте абзацы и предложения длиннее 120 символов на несколько строк по [семантическому принципу](https://sembr.org/).
  
    В отрендеренной документации мультистрочные абзацы и предложения «склеиваются» обратно.
    Это удобно при просмотре diff-ов на GitHub и GitLab и облегчает чтение исходного Markdown.
    Кроме того, это позволяет выявлять слишком длинные предложения, которые в любом случае стоит упростить.

    Переносить строку следует:

    - после точки в конце предложения;
    - после запятой или точки с запятой, если они завершают часть сложного предложения;
    - по смыслу, не разрывая логически связанную часть предложения.

## Работа с элементами документации

### Описание параметров

- Формулируйте описание так, чтобы первое предложение содержало только назначение параметра.
  Дополнительную информацию приводите в следующем абзаце.

- Отбивайте абзацы в описании пустой строкой.
  Это важно, поскольку Deckhouse UI обычно использует только первое предложение описания.

### Работа с изображениями

- При вставке изображений обязательно добавляйте подпись (alt-текст).
  Оформляйте её с заглавной буквы и без точки в конце.

### Таблицы

- Используйте таблицы для сравнения и перечисления однотипных параметров или представления повторяющихся данных.

- В заголовках колонок используйте именительный падеж единственного числа.
  По возможности делайте заголовки короткими и однозначными.

- Выравнивайте заголовки и содержимое других ячеек по левому краю.

- Начинайте заголовки и содержимое других ячеек с заглавной буквы.
  Исключение — названия параметров, модулей, статусов и другие значения,
  которые по правилам стайлгайда оформляются [в бэктиках](#бэктики).

- Не ставьте точку в конце содержимого ячеек.
  Если ячейка содержит несколько предложений, разделяйте их точками, но не ставьте точку в конце последнего предложения.

- Если значение для ячейки отсутствует или неприменимо, используйте длинное тире (`—`).

---

## Document Structure

# Структура и содержание

На этой странице содержатся рекомендации по оформлению типовых разделов документации.

## Содержимое страницы «Обзор»

Рекомендации по структуре обзорной страницы:

- **высокоуровневое объяснение темы** — что это такое и зачем это нужно;
- **контекст и место в системе** — как это вписывается в продукт;
- **основные принципы работы** — как это устроено концептуально;
- **навигация по теме** — что есть, где искать детали;
- без ухода в подробное перечисление всех объектов и сценариев.

---

## Glossary (canonical terms)

| English | Russian | Incorrect forms |
| --- | --- | --- |
| admission plugin | admission-плагин | — |
| alias | алиас | — |
| API audience | API audience | аудитория API |
| API First | API First-подход | — |
| approve | апрувить | аппрувить |
| backend | бэкенд | — |
| bare metal | bare metal | — |
| Base64 | Base64 | base64 |
| Bastion host | Bastion-хост | — |
| Bearer token authorization | Bearer-token-авторизация | — |
| binding | биндинг | — |
| bootstrap | бутстрап | — |
| breaking changes | изменения, влияющие на обратную совместимость | — |
| build | сборка | — |
| cache | кеш | кэш |
| Cloud Native application | Cloud Native-приложение | — |
| cloud provider | облачный провайдер | — |
| clusters | кластеры | кластера |
| cluster-wide resource | cluster-wide-ресурс | — |
| Code First | Code First-подход | — |
| commit | коммит | — |
| container registry | хранилище образов контейнеров | — |
| control plane | control plane | — |
| cookie files | файлы cookie | cookie-файлы |
| cordon a node | выполнить cordon узла | — |
| custom resource | кастомный ресурс | — |
| dashboard | дашборд | дэшборд |
| data plane | data plane | — |
| deployment | развёртывание | — |
| directory | директория | папка |
| Docker server | Docker-сервер | — |
| drain a node | выполнить drain узла | — |
| edition | редакция | DKP revision |
| egress gateway | egress gateway | — |
| email | email | — |
| endpoint | эндпоинт | эндпойнт |
| evict | вытеснить | удалить под, выселить под |
| (threat) exposure | подверженность (угрозам) | — |
| finding | несоответствие | — |
| firewall | файрвол | — |
| flash | флеш | флэш |
| folder | директория | папка |
| frontend | фронтенд | — |
| hash | хеш | хэш |
| healthcheck | healthcheck | — |
| histogram | гистограмма | — |
| hook | хук | — |
| ID | идентификатор | id |
| image digest | дайджест образа | — |
| infrastructure-agnostic | инфраструктурно независимый | инфраструктурно-независимый |
| ingress gateway | ingress gateway | — |
| inlet | инлет | — |
| instance class | инстанс-класс | — |
| IP address | IP-адрес | IP |
| job | задача | джоба |
| JSON file | JSON-файл | файл JSON |
| label | лейбл | тег, метка |
| landing | лендинг | — |
| load balancer | балансировщик нагрузки | — |
| master node | master-узел | мастер-узел, мастер-нода |
| module parameter | параметр модуля | — |
| multi-line string | multi-line-строка | — |
| multi-master | мультимастерный | — |
| multitenancy | мультитенантность | — |
| mutating webhook | mutating-вебхук | — |
| namespace | неймспейс | пространство имён |
| namespaced resource | namespaced-ресурс | — |
| node | узел | нода |
| node group | группа узлов | — |
| offline | офлайн | оффлайн |
| Open Source utility | Open Source-утилита | — |
| orphan token | orphan-токен | — |
| overhead | накладные расходы | — |
| patch release | патч-релиз | — |
| pipeline | пайплайн | — |
| plain text | в открытом виде | — |
| pod | под | — |
| production cluster | production-кластер | продуктивный кластер |
| production environment | production-окружение | — |
| resource field | параметр ресурса | — |
| reverse proxy | обратный прокси | — |
| rolling update | скользящее обновление | — |
| runtime | рантайм | — |
| metrics scraper | сборщик метрик | скрейпер |
| secret | секрет | — |
| security group | группа безопасности | — |
| self-signed | самоподписанный | самоподписной |
| servers | серверы | сервера |
| service | сервис | — |
| ServiceAccount | ServiceAccount | сервисный аккаунт |
| service mesh | сервис-меш | — |
| sidecar | сайдкар | — |
| single-master | с одним master-узлом | — |
| sink | приёмник | — |
| skill | скил | скилл |
| slash | слеш | слэш |
| spell checker | спелл-чекер | — |
| snapshot | снимок | снапшот, снэпшот |
| software-defined | программно-определяемый | — |
| spot instance | spot-инстанс | — |
| subagent | субагент | сабагент, подагент |
| subresource | субресурс | сабресурс, подресурс |
| symbolic link | символическая ссылка | симлинк, symlink |
| taints | taints | — |
| tag | тег | тэг |
| thick pool | thick pool | — |
| thick volume | thick-том | — |
| thin pool | thin pool | — |
| thin volume | thin-том | — |
| tolerations | tolerations | — |
| trace data | данные трассировки | — |
| tracing | трассировка | — |
| transform | преобразование | — |
| validating webhook | validating-вебхук | — |
| virtual machine | виртуальная машина | — |
| vulnerability | уязвимость | — |
| watch queries | watch-запросы | — |
| webhook | вебхук | — |
| web interface | веб-интерфейс | web-интерфейс |
| worker node | worker-узел | — |
| YAML file | YAML-файл | файл YAML |
| Alertmanager | Alertmanager | alert manager, Alert Manager, AlertManager |
| Alpine Linux | Alpine Linux | — |
| ALT Linux | ALT Linux | — |
| Amazon Machine Image | Amazon Machine Image | — |
| Apache Cassandra | Apache Cassandra | — |
| Apache ZooKeeper | Apache ZooKeeper | — |
| Argo CD | Argo CD | — |
| Astra Linux | Astra Linux | — |
| Basis Dynamix | Basis Dynamix | Базис.DynamiX |
| Bash | Bash | баш, bash |
| Buildah | Buildah | — |
| CentOS | CentOS | — |
| Cilium | Cilium | — |
| ClickHouse | ClickHouse | — |
| containerd | containerd | — |
| crictl | crictl | — |
| curl | curl | — |
| Deckhouse Kubernetes Platform | Deckhouse Kubernetes Platform | Deckhouse, Deckhouse platform, платформа Deckhouse, платформа DKP |
| Deckhouse web UI | веб-интерфейс Deckhouse | веб-интерфейс DKP |
| Dex | Dex | — |
| Docker Compose | Docker Compose | — |
| Docker Engine | Docker Engine | — |
| Docker executor | Docker executor | — |
| Docker Hub | Docker Hub | — |
| DRBD | DRBD | — |
| etcd | etcd | — |
| Fedora Linux | Fedora Linux | — |
| Flannel | Flannel | — |
| GitHub | GitHub | — |
| GitLab | GitLab | — |
| GitLab Runner | GitLab Runner | — |
| Go | Go | Golang |
| Huawei Cloud | Huawei Cloud | HuaweiCloud |
| Ingress NGINX Controller | Ingress-контроллер | — |
| JavaScript | JavaScript | — |
| jq | jq | — |
| Komodor | Komodor | — |
| kube-proxy | kube-proxy | — |
| kubectl | kubectl | — |
| kubelet | kubelet | — |
| Kubernetes | Kubernetes | куб, кубик, кубер, K8s |
| Kubernetes API | API Kubernetes | — |
| Kubernetes executor | Kubernetes executor | — |
| KubeVirt | KubeVirt | — |
| Kustomize | Kustomize | — |
| Monokle | Monokle | — |
| macOS | macOS | MacOS |
| Microsoft Teams | Microsoft Teams | — |
| Microsoft Windows | Microsoft Windows | — |
| MinIO | MinIO | — |
| Mnesia | Mnesia | — |
| MongoDB | MongoDB | — |
| MySQL | MySQL | — |
| New Relic | New Relic | — |
| Node.js | Node.js | — |
| Okagent | Okagent | — |
| OpenSearch | OpenSearch | — |
| OpenShift | OpenShift | — |
| OpenSSL | OpenSSL | Open SSL |
| OpenVPN | OpenVPN | Open VPN |
| PostgreSQL | PostgreSQL | — |
| PowerShell | PowerShell | — |
| RabbitMQ | RabbitMQ | — |
| Redis | Redis | — |
| RED OS | РЕД ОС | — |
| Rust | Rust | — |
| scheduler | планировщик | — |
| Sentry | Sentry | — |
| Slack | Slack | — |
| Terraform | Terraform | — |
| Trivy | Trivy | — |
| TRON ASOC | TRON ASOC | TRON.ASOC |
| Ubuntu | Ubuntu | — |
| VictoriaMetrics | VictoriaMetrics | — |
| Vue.js | Vue.js | — |
| werf | werf | — |
| Yandex Cloud | Yandex Cloud | YandexCloud, Яндекс Клауд |
| B2B | B2B | — |
| CRD | CRD | — |
| E2E | E2E | — |
| Elasticsearch, Fluentd, and Kibana (EFK) stack | стек Elasticsearch, Fluentd и Kibana (EFK) | — |
| Elasticsearch, Logstash, and Kibana (ELK) stack | стек Elasticsearch, Logstash и Kibana (ELK) | — |
| IOPS | IOPS | — |
| RBAC | RBAC | — |
| SaaS | SaaS | — |