# Посібник зі стилю документації LLMS index: [llms.txt](/llms.txt) --- Ця сторінка надає вказівки щодо стилю написання документації Kubernetes. Це вказівки, а не правила. Використовуйте здоровий глузд та не соромтеся пропонувати зміни до цього документа за допомогою pull request. Для отримання додаткової інформації про створення нового вмісту для документації Kubernetes, прочитайте [Посібник з вмісту документації](/docs/contribute/style/content-guide/). Зміни до посібника зі стилю вносяться групою SIG Docs. Щоб запропонувати зміну або доповнення, [додайте її до порядку денного](https://bit.ly/sig-docs-agenda) на наступну зустріч SIG Docs та відвідайте зустріч, щоб взяти участь в обговоренні. ## Мова {#language} Документація Kubernetes була перекладена кількома мовами (див. [локалізовані файли README](https://github.com/kubernetes/website/blob/main/README.md#localization-readmemds)). Процес локалізації документації для інших мови описано в розділі[Локалізація документації Kubernetes](/docs/contribute/localization/). Документація англійською мовою використовує правопис та граматику американської англійської. ## Стандарти форматування документації {#documentation-formatting-standards} ### Використовуйте UpperCamelCase для обʼєктів API {#use-upper-camel-case-for-api-objects} Коли ви посилаєтеся на взаємодію з обʼєктом API, використовуйте [UpperCamelCase](https://uk.wikipedia.org/wiki/CamelCase), також відомий як Pascal case. Ви можете зустріти інші варіанти написання, наприклад, "configMap", в [Довіднику API](/docs/reference/kubernetes-api/). У загальній документації краще використовувати UpperCamelCase, називаючи обʼєкт "ConfigMap". Коли ви загалом обговорюєте обʼєкт API, використовуйте [велику літеру тільки на початку речення](https://docs.microsoft.com/en-us/style-guide/text-formatting/using-type/use-sentence-style-capitalization). Наведені нижче приклади зосереджуються на капіталізації. Для отримання додаткової інформації про форматування імен обʼєктів API перегляньте відповідні рекомендації щодо [Стилю коду](#code-style-inline-code).
Як робити та не робити — Використовуйте Pascal case для обʼєктів API
Рекомендовано Небажано
Ресурс HorizontalPodAutoscaler відповідає за ... Horizontal pod autoscaler відповідає за ...
Обʼєкт PodList є списком Podʼів. Обʼєкт Pod List є списком Podʼів.
Обʼєкт Volume містить поле hostPath. Обʼєкт volume містить поле hostPath.
Кожен обʼєкт ConfigMap є частиною простору імен. Кожен обʼєкт configMap є частиною простору імен.
Для управління конфіденційними даними розгляньте можливість використання API Secret. Для управління конфіденційними даними розгляньте можливість використання secret API.
### Використовуйте кутові дужки для заповнювачів {#use-angle-brackets-for-placeholders} Використовуйте кутові дужки для заповнювачів. Поясніть читачеві, що представляє заповнювач, наприклад: Показ інформацію про Pod: ```shell kubectl describe pod -n ``` Якщо простір імен Podʼа є `default`, ви можете пропустити параметр `-n`. ### Використовуйте жирний шрифт для елементів інтерфейсу користувача {#use-bold-for-ui-elements}
Як робити та не робити — Жирний шрифт для елементів інтерфейсу
Рекомендовано Небажано
Натисніть Fork. Натисніть "Fork".
Виберіть Other. Виберіть "Other".
### Використовуйте курсив для визначення або введення нових термінів {#use-italics-to-define-or-introduce-new-terms}
Як робити та не робити — Використання курсиву для нових термінів
Рекомендовано Небажано
Кластер — це набір вузлів ... "Кластер" — це набір вузлів ...
Ці компоненти утворюють панель управління. Ці компоненти утворюють панель управління.
### Використовуйте стиль коду для імен файлів, тек та шляхів {#use-code-style-for-file-names-dirs-and-paths}
Як робити та не робити — Використовуйте кодовий стиль для імен файлів, тек та шляхів
Рекомендовано Небажано
Відкрийте файл envars.yaml. Відкрийте файл envars.yaml.
Перейдіть до теки /docs/tutorials. Перейдіть до теки /docs/tutorials.
Відкрийте файл /_data/concepts.yaml. Відкрийте файл /_data/concepts.yaml.
### Використовуйте міжнародний стандарт для пунктуації всередині лапок {#use-international-standard-for-punctuation-inside-quotes}
Як робити та не робити — Використовуйте міжнародний стандарт для пунктуації всередині лапок
Рекомендовано Небажано
Події записуються з відповідною "стадією". Події записуються з відповідною "стадією."
Копія називається "fork". Копія називається "fork."
### Використовуйте першу велику літеру для фаз підвищення рівня вдосконалення {#use-start-case-for-enhancement-graduation-phases}
Як робити та не робити — Використовуйте першу велику літеру для фаз підвищення рівня вдосконалення
Рекомендовано Небажано
Dynamic Resource Allocation (DRA) тепер в Beta. Dynamic Resource Allocation (DRA) тепер в beta.
## Форматування вбудованого коду {#inline-code-formatting} ### Використовуйте кодовий стиль для вбудованого коду та команд {#code-style-inline-code} Для вбудованого в документі HTML коду використовуйте теґ ``. У документі Markdown використовуйте зворотну лапку (`` ` ``). Проте, API обʼєкти, такі як StatefulSet або ConfigMap, пишуться дослівно (без зворотних лапок); це дозволяє використовувати апострофи для позначення присвійного відмінка.
Як робити та не робити — Використовуйте стиль code для вбудованого коду, команд та API обʼєктів
Рекомендовано Небажано
Команда kubectl run створює Pod. Команда "kubectl run" створює Pod.
Kubelet на кожному вузлі отримує Lease... Kubelet на кожному вузлі отримує Lease...
PersistentVolume представляє довговічне сховище... PersistentVolume представляє довговічне сховище...
Поле .spec.group у CustomResourceDefinition... Поле CustomResourceDefinition.spec.group у CustomResourceDefinition...
Для декларативного управління використовуйте kubectl apply. Для декларативного управління використовуйте "kubectl apply".
Огортайте приклади коду потрійними зворотними лапками. (```) Огортайте приклади коду будь-яким іншим синтаксисом.
Використовуйте одинарні зворотні лапки для вбудованого коду. Наприклад, var example = true. Використовуйте дві зірочки (**) або підкреслення (_) для вбудованого коду. Наприклад, var example = true.
Використовуйте потрійні зворотні лапки перед і після багаторядкового блоку коду для виділених блоків коду. Використовуйте багаторядкові блоки коду для створення діаграм, блок-схем або інших ілюстрацій.
Використовуйте значущі імена змінних, які мають контекст. Використовуйте імена змінних, такі як 'foo', 'bar', і 'baz', які не є значущими та не мають контексту.
Видаляйте пробіли в кінці рядків коду. Додавайте пробіли в кінці рядків коду, коли вони важливі, оскільки інструмент читання тексту з екрана також озвучує пробіли.
### Використовуйте стиль коду для імен полів обʼєктів та просторів імен {#use-code-style-for-object-field-names-and-namespaces}
Як робити та не робити — Використовуйте кодовий стиль для імен полів обʼєктів
Рекомендовано Небажано
Встановіть значення поля replicas у конфігураційному файлі. Встановіть значення поля "replicas" у конфігураційному файлі.
Значення поля exec є обʼєктом ExecAction. Значення поля "exec" є обʼєктом ExecAction.
Запустіть процес як DaemonSet у просторі імен kube-system. Запустіть процес як DaemonSet у просторі імен kube-system.
### Використовуйте стиль коду для назв команд, інструментів та компонентів Kubernetes {#use-code-style-for-kubernetes-command-tool-and-component-names}
Як робити та не робити — Використовуйте кодовий стиль для назв командних інструментів та компонентів Kubernetes
Рекомендовано Небажано
kubelet підтримує стабільність вузла. Kubelet підтримує стабільність вузла.
kubectl відповідає за знаходження та автентифікацію на API сервері. Kubectl відповідає за знаходження та автентифікацію на apiserver.
Запустіть процес із сертифікатом, kube-apiserver --client-ca-file=FILENAME. Запустіть процес із сертифікатом, kube-apiserver --client-ca-file=FILENAME.
### Початок речення з назви інструменту або компонента {#starting-a-sentence-with-a-component-tool-or-component-name}
Як робити та не робити — Початок речення з назви інструменту або компонента
Рекомендовано Небажано
The kubeadm tool bootstraps and provisions machines in a cluster. kubeadm tool bootstraps and provisions machines in a cluster.
The kube-scheduler is the default scheduler for Kubernetes. kube-scheduler is the default scheduler for Kubernetes.
### Використовуйте загальний дескриптор замість назви компонента {#use-a-general-descriptor-over-a-component-name}
Як робити та не робити — Використовуйте загальний дескриптор замість назви компонента
Рекомендовано Небажано
API сервер Kubernetes пропонує специфікацію OpenAPI. Apiserver пропонує специфікацію OpenAPI.
Агреговані API є підпорядкованими API серверами. Агреговані API є підпорядкованими APIServers.
### Використовуйте звичайний стиль для значень полів типу string та integer {#use-normal-style-for-string-and-integer-field-values} Для значень полів типу string або integer використовуйте звичайний стиль без лапок.
Як робити та не робити — Використовуйте нормальний стиль для значень полів типу string та integer
Рекомендовано Небажано
Встановіть значення imagePullPolicy на Always. Встановіть значення imagePullPolicy на "Always".
Встановіть значення image на nginx:1.16. Встановіть значення image на nginx:1.16.
Встановіть значення поля replicas на 2. Встановіть значення поля replicas на 2.
Однак, розгляньте можливість цитування значень у випадках, коли є ризик, що читачі можуть сплутати значення з типом API. ## Посилання на API ресурси Kubernetes {#referring-to-kubernetes-api-resources} Цей розділ описує, як ми посилаємося на API ресурси в документації. ### Уточнення щодо терміна "ресурс" {#clarification-about-resource} Kubernetes використовує слово _ресурс_ для позначення ресурсів API. Наприклад, шлях URL `/apis/apps/v1/namespaces/default/deployments/my-app` представляє Deployment з назвою "my-app" у просторі імен "default". У термінології HTTP, простір імен є ресурсом — так само як всі веб-URL ідентифікують ресурс. Документація Kubernetes також використовує "ресурс" для опису запитів і обмежень на використання процесорів і памʼяті. Дуже часто доцільно посилатися на API ресурси як на "API ресурси", щоб уникнути плутанини з процесорними ресурсами та ресурсами памʼяті або з іншими видами ресурсів. Якщо ви використовуєте назву ресурсу в нижньому регістрі у множині, наприклад, `deployments` або `configmaps`, надайте додатковий контекст, щоб допомогти читачам зрозуміти, що ви маєте на увазі. Якщо ви використовуєте цей термін у контексті, де також можна використовувати назву в UpperCamelCase, і є ризик неоднозначності, розгляньте можливість використання типу API в UpperCamelCase. ### Коли використовувати терміни Kubernetes API {#when-to-use-kubernetes-api-terminologies} Різні терміни Kubernetes API включають: - _API типи (kind)_: назви, які використовуються в URL API (такі як `pods`, `namespaces`). API типи іноді також називають _типами ресурсів_. - _API ресурс_: одиничні екземпляри API типу (такі як `pod`, `secret`). - _Обʼєкт_: ресурс, який служить як "запис наміру". Обʼєкт є бажаним станом для конкретної частини вашого кластера, який намагається підтримувати панель управління Kubernetes. Всі обʼєкти в API Kubernetes також є ресурсами. Для ясності ви можете додати "ресурс" або "обʼєкт", коли посилаєтесь на API ресурс у документації Kubernetes. Наприклад: пишіть "обʼєкт Secret", замість "Secret". Якщо з контексту зрозуміло, що мова йде про ресурс, можна не додавати це слово. Розгляньте можливість перефразування, коли це допомагає уникнути непорозумінь. Звичайною ситуацією є випадок, коли ви хочете почати речення з API типу, наприклад, "Secret"; оскільки в англійській та інших мовах заголовні літери використовуються на початку речень, читачі не можуть визначити, чи маєте ви на увазі API тип або загальне поняття. Перефразування може допомогти. ### Назви API ресурсів {#api-resource-names} Завжди форматуйте назви API ресурсів, використовуючи [UpperCamelCase](https://uk.wikipedia.org/wiki/Camel_case), також відомий як PascalCase. Не пишіть API типи з використанням форматування коду. Не розбивайте назву API обʼєкта на окремі слова. Наприклад, використовуйте PodTemplateList, а не Pod Template List. Для отримання додаткової інформації про PascalCase і форматування коду, ознайомтесь із відповідними рекомендаціями щодо [Використання UpperCamelCase для API обʼєктів](/docs/contribute/style/style-guide/#use-upper-camel-case-for-api-objects) та [Використання кодового стилю для вбудованого коду, команд і API обʼєктів](#code-style-inline-code). Для отримання додаткової інформації про термінологію Kubernetes API, ознайомтесь із відповідними рекомендаціями щодо [Термінології API Kubernetes](/docs/reference/using-api/api-concepts/#standard-api-terminology). ## Форматування фрагментів коду {#code-snippet-formatting} ### Не включайте символ командного рядка {#don-t-include-the-command-prompt}
Як робити та не робити — Не включайте командний рядок
Рекомендовано Небажано
kubectl get pods $ kubectl get pods
### Відокремлюйте команди від їх виводу {#separate-commands-from-output} Переконайтеся, що Pod працює на обраному вами вузлі: ```shell kubectl get pods --output=wide ``` Результат буде схожим на цей: ```console NAME READY STATUS RESTARTS AGE IP NODE nginx 1/1 Running 0 13s 10.200.0.4 worker0 ``` ### Версіювання прикладів для Kubernetes {#versioning-kubernetes-examples} Приклади коду та конфігурацій, які включають інформацію про версії, повинні бути узгоджені з текстом. Якщо інформація є специфічною для версії, версія Kubernetes повинна бути визначена у розділі `prerequisites` [шаблону Task](/docs/contribute/style/page-content-types/#task) або шаблону [Tutorial](/docs/contribute/style/page-content-types/#tutorial). Після збереження сторінки, розділ `prerequisites` буде показаний з назвою — **Перед тим, як почати**. Щоб вказати версію Kubernetes для сторінки з завданням або навчальним посібником, включіть `min-kubernetes-server-version` у front matter сторінки. Якщо YAML приклад знаходиться у файлі окремо, знайдіть та перегляньте теми, які включають його як посилання. Переконайтеся, що будь-які теми, які використовують окремий YAML, мають відповідну інформацію про версії. Якщо окремий YAML файл не посилається на жодні теми, розгляньте можливість його видалення замість оновлення. Наприклад, якщо ви пишете навчальний посібник, що стосується версії Kubernetes 1.8, front matter вашого markdown файлу мають виглядати приблизно так: ```yaml --- title: <ваша назва навчального посібника> min-kubernetes-server-version: v1.8 --- ``` У прикладах коду та конфігурацій не включайте коментарі про альтернативні версії. Будьте обережні, щоб не включати некоректні твердження у ваші приклади у вигляді коментарів, наприклад: ```yaml apiVersion: v1 # попередні версії використовують... kind: Pod ... ``` ## Формули та рівняння {#formulae-and-equations} Ви можете скористатися підтримкою Docsy для [схем і формул](https://www.docsy.dev/docs/adding-content/diagrams-and-formulae/#latex-support-with-katex). Наприклад: `\\(\frac{7}{9} \sqrt{K^8 s}\\)`, що буде перетворено у \\(\frac{7}{9} \sqrt{K^8 s}\\). Надавайте перевагу вбудованим формулам там, де це доцільно, але ви можете використовувати блок `math`, якщо це може допомогти читачам. Прочитайте посібник Docsy, щоб дізнатися, що потрібно змінити на вашій сторінці, щоб активувати підтримку; якщо у вас виникли проблеми, додайте `math: true` до [front matter](https://gohugo.io/content-management/front-matter/) сторінки (ви можете зробити це, навіть якщо вважаєте, що автоматичної активації має бути достатньо). ## Словник Kubernetes.io {#kubernetes-io-word-list} Список специфічних для Kubernetes термінів і слів, які слід використовувати послідовно у всьому сайті.
Словник Kubernetes.io
Термін Використання
Kubernetes Kubernetes завжди має писатися з великої літери.
Docker Docker завжди має писатися з великої літери.
SIG Docs SIG Docs, а не SIG-DOCS чи інші варіанти.
On-premises On-premises або On-prem, а не On-premise чи інші варіанти.
cloud native Cloud native або cloud native, залежно від структури речення, а не cloud-native чи Cloud Native.
open source Open source або open source, залежно від структури речення, а не open-source чи Open Source.
## Shortcodes {#shortcodes} Hugo [Shortcodes](https://gohugo.io/content-management/shortcodes) допомагають створювати різні рівні риторичної привабливості. Наша документація підтримує три варіанти шорткоду [`alert`](https://www.docsy.dev/docs/adding-content/shortcodes/#alert) Docsy у цій категорії: **Note**, **Caution** та **Warning**. 1. Вставте текст між початковим і кінцевим шорткодом `alert`, вказавши атрибути `color` та `title` відповідно до потрібного варіанту. 2. Використовуйте наступний синтаксис для застосування стилю: ```none {{< alert color="info" title="Note" >}} Шорткод рендерить заголовок як заголовок, тому не повторюйте його всередині тіла. {{< /alert >}} ``` Вихідний результат: Багато сторінок все ще використовують застарілі шорткоди `{{< note >}}`, `{{< caution >}}` та `{{< warning >}}`. Вони все ще працюють — надавайте перевагу шорткоду `alert` для нового вмісту та під час редагування наявних сторінок. ### Note {#note} Використовуйте `{{< alert color="info" title="Note" >}}` для виділення поради або корисної інформації. Наприклад: ```hugo {{< alert color="info" title="Note" >}} Ви _все ще_ можете використовувати Markdown всередині цих виносок. {{< /alert >}} ``` Вихідний результат: Ви можете використовувати шорткод `alert` у списку: ```md 1. Використовуйте шорткод alert у списку 1. Другий пункт з вбудованою приміткою {{< alert color="info" title="Note" >}} Шорткоди Warning, Caution і Note, вбудовані у списки, потребують відступу в чотири пробіли. Див. [Поширені проблеми з шорткодами](#common-shortcode-issues). {{< /alert >}} 1. Третій пункт у списку 1. Четвертий пункт у списку ``` Вихідний результат: 1. Використовуйте шорткод alert у списку 1. Другий пункт з вбудованою приміткою 1. Третій пункт у списку 1. Четвертий пункт у списку ### Caution {#caution} Використовуйте `{{< alert color="caution" title="Увага" >}}` для привернення уваги до важливої інформації, щоб уникнути помилок. Наприклад: ```hugo {{< alert color="caution" title="Увага" >}} Стиль виклику застосовується лише до рядка безпосередньо над теґом. {{< /alert >}} ``` Результат: ### Warning {#warning} Використовуйте `{{< alert color="danger" title="Попередження" >}}` для вказівки на небезпеку або важливу інформацію, яку потрібно обовʼязково враховувати. Наприклад: ```hugo {{< alert color="danger" title="Попередження" >}} Будьте обережні. {{< /alert >}} ``` Вихідний результат: ## Поширені проблеми з Shortcode {#common-shortcode-issues} ### Нумеровані списки {#ordered-lists} Shortcode переривають нумеровані списки, якщо не зробити відступ у чотири пробіли перед сповіщенням та теґом. Наприклад: 1. Розігрійте духовку до 350˚F 1. Приготуйте тісто та вилийте його у форму. {{< alert color="info" title="Примітка" >}}Змастіть форму для кращих результатів.{{< /alert >}} 1. Випікайте 20-25 хвилин або до готовності. Вихідний результат: 1. Розігрійте духовку до 350˚F 1. Приготуйте тісто та вилийте його у форму. 1. Випікайте 20-25 хвилин або до готовності. ### Вирази Include {#include-statements} Шорткоди всередині виразів include зламають збірку. Необхідно вставити їх у батьківський документ до і після виклику include. Наприклад: ```hugo {{< alert color="info" title="Примітка" >}} {{< include "task-tutorial-prereqs.md" >}} {{< /alert >}} ``` ## Елементи Markdown {#markdown-elements} ### Переноси рядків {#line-breaks} Використовуйте один символ переносу рядка (`\n`) для розділення контенту на рівні блоків, таких як заголовки, списки, зображення, блоки коду тощо. Винятком є заголовки другого рівня, де необхідно зробити два переноси рядка. Заголовки другого рівня слідують після заголовків першого рівня (або заголовка) без передуючих абзаців або тексту. Два переноси рядка допомагають краще візуалізувати загальну структуру контенту в текстовому редакторі. Ручне перенесення абзаців у вихідному коді Markdown є доречним, оскільки інструмент git та сайт GitHub генерують порівняння файлів на основі рядків. Ручне перенесення довгих рядків допомагає рецензентам легко знаходити зміни у PR і надавати зворотний звʼязок. Це також допомагає командам, які займаються локалізацією, відслідковувати зміни на рівні рядків[^1]. Перенесення рядка може відбуватися в кінці речення або після знака пунктуації. Винятком є випадки, коли Markdown-посилання або шорткод очікується в одному рядку. [^1]: Це твердження є хибним оскільки такий підхід ускладнює виконання перекладів речень які в початковому тексті розділені на кілька рядків. Розбивання речення на кілька рядків унеможлювлює використання систем роботи з перекладами, що працюють на рівні рядків, а не речень. В середині речень не має бути переносів на новий рядок!!! ### Заголовки та назви {#headings} Користувачі цієї документації можуть використовувати інструменти озвучування тексту (екранний зчитувач) або іншу допоміжну технологію (AT). [Екранні зчитувачі](https://en.wikipedia.org/wiki/Screen_reader) є лінійними вихідними пристроями, що виводять елементи на сторінку по одному. Якщо на сторінці багато контенту, ви можете використовувати заголовки для створення внутрішньої структури сторінки. Гарна структура сторінки допомагає всім користувачам легко орієнтуватися на сторінці або фільтрувати теми, які їх цікавлять.
Рекомендовані та не рекомендовані приклади використання заголовків
Рекомендовано Небажано
Оновлюйте заголовок у метаданих сторінки або блогу. Використовуйте заголовки першого рівня, оскільки Hugo автоматично перетворює заголовок у метаданих сторінки на заголовок першого рівня.
Використовуйте впорядковані заголовки для надання змістовного високорівневого конспекту вашого контенту. Використовуйте заголовки рівнів 4-6, якщо це абсолютно необхідно. Якщо ваш контент настільки деталізований, можливо, його слід розбити на окремі статті.
Використовуйте символи фунта або решітки (#) для контенту, що не відноситься до блогу. Використовуйте підкреслення (--- або ===) для позначення заголовків першого рівня.
Використовуйте "sentence case" (великі літери тільки на початку речення) для заголовків у тілі сторінки. Наприклад, Розширення kubectl за допомогою втулків Використовуйте "title case" (великі літери на початку кожного слова) для заголовків у тілі сторінки. Наприклад, Розширення Kubectl За Допомогою Втулків
Використовуйте "title case" для заголовків сторінок у метаданих. Наприклад, title: Kubernetes API Server Bypass Risks Використовуйте "sentence case" для заголовків сторінок у метаданих. Наприклад, не використовуйте title: Kubernetes API server bypass risks
Розмістіть відповідні посилання в основному тексті. Використовуйте гіперпосилання (<a href=""></a>) у заголовках.
Для позначення заголовків використовуйте знаки фунтів або хешу (#). Використовуйте жирний текст або інші індикатори для розділення абзаців.
### Абзаци {#paragraphs}
Рекомендовані та не рекомендовані приклади використання абзаців
Рекомендовано Небажано
Намагайтеся, щоб абзаци не перевищували 6 речень. Не відступайте перший абзац пробілами. Наприклад, ⋅⋅⋅Три пробіли перед абзацом зроблять його абзацем з відступом.
Використовуйте три дефіси (---), щоб створити горизонтальну лінію. Використовуйте горизонтальні лінії для розділення контенту в абзацах. Наприклад, зміна сцени в історії або зміна теми в розділі. Не використовуйте горизонтальні лінії для декорацій.
### Посилання {#links}
Рекомендовані та не рекомендовані приклади використання посилань
Рекомендовано Небажано
Створюйте гіперпосилання, що надають контекст для dvscne, на який вони посилаються. Наприклад: Деякі порти на ваших машинах відкриті. Дивіться Перевірка необхідних портів для деталей. Використовуйте неоднозначні терміни, такі як "натисніть тут". Наприклад: Деякі порти на ваших машинах відкриті. Дивіться тут для деталей.
Створюйте посилання в стилі Markdown: [текст посилання](URL). Наприклад: [Hugo shortcodes](/docs/contribute/style/hugo-shortcodes/#table-captions) і вихід буде Hugo shortcodes. Використовуйте посилання в стилі HTML: <a href="/media/examples/link-element-example.css" target="_blank">Відвідайте наш підручник!</a>, або створюйте посилання, що відкриваються в нових вкладках або вікнах. Наприклад: [приклад сайту](https://example.com){target="_blank"}
### Списки {#lists} Групуйте елементи в списках, які повʼязані між собою і повинні зʼявлятися у певному порядку або для позначення кореляції між кількома елементами. Коли екранний зчитувач натрапляє на список, незалежно від того, чи це упорядкований або неупорядкований список, він оголошує користувачеві, що є група елементів списку. Потім користувач може використовувати клавіші зі стрілками для переміщення між різними елементами списку. - Закінчуйте кожен елемент у списку крапкою, якщо один або більше елементів у списку є завершеними реченнями. Для збереження послідовності зазвичай всі елементи або жоден з них мають бути завершеними реченнями. - Використовуйте цифру один з крапкою (`1.`) для упорядкованих списків. - Використовуйте (`+`), (`*`), або (`-`) для неупорядкованих списків, але якийсь один з цих символів у одному тексті (уникайте їх змішування) - Залишайте порожній рядок після кожного списку. - Відступайте вкладені списки на відповідну кількість пробілів, так щоб сімвол початку елемента спіску був на рівні з початком тексту елемента вищого рівня (наприклад, ⋅⋅⋅). - Елементи списку можуть складатися з кількох абзаців. Кожен наступний абзац у пункті списку повинен бути відступлений нарівень початку тексту елементу списку або один табулятор. ### Таблиці {#tables} Семантична мета таблиці — це представлення табличних даних. Користувачі з гарним зором можуть швидко сканувати таблицю, але екранний зчитувач проходить її рядок за рядком. Підпис таблиці використовується для створення описового заголовка для таблиці даних. Допоміжні технології (AT) використовують елемент підпису HTML для таблиці, щоб ідентифікувати вміст таблиці користувачеві в межах структури сторінки. - Додавайте підписи до таблиць за допомогою [shortcodes Hugo](/docs/contribute/style/hugo-shortcodes/#table-captions) для таблиць. ## Рекомендації щодо створення контенту {#content-best-practices} Цей розділ містить рекомендації для створення чіткого, лаконічного і послідовного контенту. ### Використовуйте теперішній час {#use-present-tense}
Рекомендовані та не рекомендовані приклади використання теперішнього часу
Рекомендовано Не рекомендовано
Ця команда запускає проксі. Ця команда запустить проксі.
Виняток: Використовуйте майбутній або минулий час, якщо це необхідно для передачі правильного значення. ### Використовуйте активний стан {#use-active-voice}
Рекомендовані та не рекомендовані приклади використання активного стану
Рекомендовано Не рекомендовано
Ви можете дослідити API за допомогою оглядача. API можна дослідити за допомогою оглядача.
Файл YAML визначає кількість реплік. Кількість реплік визначена у файлі YAML.
Виняток: Використовуйте пасивний стан, якщо активний стан призводить до незручної конструкції. ### Використовуйте просту і пряму мову {#use-simple-and-direct-language} Використовуйте просту і пряму мову. Уникайте використання зайвих фраз, наприклад, слова "будь ласка".
Рекомендовані та не рекомендовані приклади використання простої і прямої мови
Рекомендовано Не рекомендовано
Щоб створити ReplicaSet, ... Для того щоб створити ReplicaSet, ...
Дивіться конфігураційний файл. Будь ласка, дивіться конфігураційний файл.
Перегляньте Podʼи. За допомогою наступної команди ми переглянемо Podʼи.
### Звертайтесь до читача на "ви"
Рекомендовані та не рекомендовані приклади звернення до читача
Рекомендовано Не рекомендовано
Ви можете створити Deployment за допомогою ... Ми створимо Deployment за допомогою ...
У попередньому виводі ви можете побачити... У попередньому виведенні ми можемо бачити ...
### Уникайте латинських фраз {#avoid-latin-phrases} Віддавайте перевагу англійським (місцевим) термінам замість латинських абревіатур.
Рекомендовані та не рекомендовані приклади уникнення латинських фраз
Рекомендовано Не рекомендовано
For example (Наприклад), ... e.g., ...
That is (Тобто), ... i.e., ...
Виняток: Використовуйте "etc." (et cetera) для позначення "та інше". ## Шаблони, яких слід уникати {#patterns-to-avoid} ### Уникайте використання "ми" {#avoid-using-we} Використання "ми" у реченні може бути заплутаним, оскільки читач може не знати, чи є він частиною "ми", про яке ви говорите.
Рекомендовані та не рекомендовані приклади використання "ми"
Рекомендовано Не рекомендовано
Версія 1.4 включає ... У версії 1.4 ми додали ...
Kubernetes надає нову функцію для ... Ми надаємо нову функцію ...
Ця сторінка навчить вас, як використовувати Podʼи. На цій сторінці ми навчимося про Podʼи.
### Уникайте жаргону та ідіом {#avoid-jargon-and-idioms} Для багатьох читачів англійська є другою мовою. Уникайте жаргону та ідіом, щоб допомогти їм краще зрозуміти тему.
Правильні і неправильні приклади уникання жаргону та ідіом
Рекомендовано Не рекомендовано
Internally, ... Under the hood, ...
Create a new cluster. Turn up a new cluster.
### Уникайте тверджень про майбутнє {#avoid-statements-about-the-future} Уникайте обіцянок або натяків на майбутнє. Якщо вам потрібно говорити про функцію в альфа-версії, розмістіть текст під заголовком, який позначає його як альфа-інформацію. Винятком з цього правила є документація про оголошені застарівання функцій, які плануються до видалення в майбутніх версіях. Один з прикладів такої документації — [Посібник з міграції із застарілих API](/docs/reference/using-api/deprecation-guide/). ### Уникайте тверджень, які незабаром стануть неактуальними {#avoid-statements-that-will-soon-be-out-of-date} Уникайте слів таких як "зараз" і "новий". Функція, яка є новою сьогодні, може не вважатися новою через кілька місяців.
Правильні і неправильні приклади уникання тверджень, які незабаром стануть застарілими
Рекомендовано Не рекомендовано
У версії 1.4, ... У поточній версії, ...
Функція Federation надає ... Нова функція Federation надає ...
### Уникайте слів, що припускають певний рівень розуміння {#avoid-words-that-assume-a-specific-level-of-understanding} Уникайте слів таких як "просто", "легко", "зрозуміло". Ці слова не додають цінності.
Правильні і неправильні приклади уникання слів, що припускають певний рівень розуміння
Рекомендовано Не рекомендовано
Включіть одну команду в ... Включіть просто одну команду в ...
Запустіть контейнер ... Продовжте запускати контейнер ...
Ви можете видалити ... Ви можете легко видалити ...
Ці кроки ... Ці прості кроки ...
### Файл EditorConfig {#editorconfig-file} Проєкт Kubernetes підтримує файл EditorConfig, який встановлює загальні стилістичні уподобання в текстових редакторах, таких як VS Code. Ви можете використовувати цей файл, якщо хочете переконатися, що ваші внески відповідають решті проєкту. Щоб переглянути файл, зверніться до [`.editorconfig`](https://github.com/kubernetes/website/blob/main/.editorconfig) в кореневій теці репозиторію. ## Що далі - Дізнайтеся про [написання нової теми](/docs/contribute/style/write-new-topic/). - Дізнайтеся про [використання шаблонів сторінок](/docs/contribute/style/page-content-types/). - Дізнайтеся про [власні hugo shortcodes](/docs/contribute/style/hugo-shortcodes/). - Дізнайтеся про [створення pull request](/docs/contribute/new-content/open-a-pr/).