Посібник зі стилю документації

Ця сторінка надає вказівки щодо стилю написання документації Kubernetes. Це вказівки, а не правила. Використовуйте здоровий глузд та не соромтеся пропонувати зміни до цього документа за допомогою pull request.

Для отримання додаткової інформації про створення нового вмісту для документації Kubernetes, прочитайте Посібник з вмісту документації.

Зміни до посібника зі стилю вносяться групою SIG Docs. Щоб запропонувати зміну або доповнення, додайте її до порядку денного на наступну зустріч SIG Docs та відвідайте зустріч, щоб взяти участь в обговоренні.

Мова

Документація Kubernetes була перекладена кількома мовами (див. локалізовані файли README).

Процес локалізації документації для інших мови описано в розділіЛокалізація документації Kubernetes.

Документація англійською мовою використовує правопис та граматику американської англійської.

Стандарти форматування документації

Використовуйте UpperCamelCase для обʼєктів API

Коли ви посилаєтеся на взаємодію з обʼєктом API, використовуйте UpperCamelCase, також відомий як Pascal case. Ви можете зустріти інші варіанти написання, наприклад, "configMap", в Довіднику API. У загальній документації краще використовувати UpperCamelCase, називаючи обʼєкт "ConfigMap".

Коли ви загалом обговорюєте обʼєкт API, використовуйте велику літеру тільки на початку речення.

Наведені нижче приклади зосереджуються на капіталізації. Для отримання додаткової інформації про форматування імен обʼєктів API перегляньте відповідні рекомендації щодо Стилю коду.

Використовуйте кутові дужки для заповнювачів

Використовуйте кутові дужки для заповнювачів. Поясніть читачеві, що представляє заповнювач, наприклад:

Показ інформацію про Pod:

kubectl describe pod <pod-name> -n <namespace>

Якщо простір імен Podʼа є default, ви можете пропустити параметр -n.

Використовуйте жирний шрифт для елементів інтерфейсу користувача

Використовуйте курсив для визначення або введення нових термінів

Використовуйте стиль коду для імен файлів, тек та шляхів

Використовуйте міжнародний стандарт для пунктуації всередині лапок

Форматування вбудованого коду

Використовуйте кодовий стиль для вбудованого коду та команд

Для вбудованого в документі HTML коду використовуйте теґ <code>. У документі Markdown використовуйте зворотну лапку (`). Проте, API обʼєкти, такі як StatefulSet або ConfigMap, пишуться дослівно (без зворотних лапок); це дозволяє використовувати апострофи для позначення присвійного відмінка.

Використовуйте стиль коду для імен полів обʼєктів та просторів імен

Використовуйте стиль коду для назв команд, інструментів та компонентів Kubernetes

Початок речення з назви інструменту або компонента

Використовуйте загальний дескриптор замість назви компонента

Використовуйте звичайний стиль для значень полів типу string та integer

Для значень полів типу string або integer використовуйте звичайний стиль без лапок.

Однак, розгляньте можливість цитування значень у випадках, коли є ризик, що читачі можуть сплутати значення з типом API.

Посилання на API ресурси Kubernetes

Цей розділ описує, як ми посилаємося на API ресурси в документації.

Уточнення щодо терміна "ресурс"

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

Різні терміни 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 ресурсів, використовуючи UpperCamelCase, також відомий як PascalCase. Не пишіть API типи з використанням форматування коду.

Не розбивайте назву API обʼєкта на окремі слова. Наприклад, використовуйте PodTemplateList, а не Pod Template List.

Для отримання додаткової інформації про PascalCase і форматування коду, ознайомтесь із відповідними рекомендаціями щодо Використання UpperCamelCase для API обʼєктів та Використання кодового стилю для вбудованого коду, команд і API обʼєктів.

Для отримання додаткової інформації про термінологію Kubernetes API, ознайомтесь із відповідними рекомендаціями щодо Термінології API Kubernetes.

Форматування фрагментів коду

Не включайте символ командного рядка

Відокремлюйте команди від їх виводу

Переконайтеся, що Pod працює на обраному вами вузлі:

kubectl get pods --output=wide

Результат буде схожим на цей:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Версіювання прикладів для Kubernetes

Приклади коду та конфігурацій, які включають інформацію про версії, повинні бути узгоджені з текстом.

Якщо інформація є специфічною для версії, версія Kubernetes повинна бути визначена у розділі prerequisites шаблону Task або шаблону Tutorial. Після збереження сторінки, розділ prerequisites буде показаний з назвою — Перед тим, як почати.

Щоб вказати версію Kubernetes для сторінки з завданням або навчальним посібником, включіть min-kubernetes-server-version у front matter сторінки.

Якщо YAML приклад знаходиться у файлі окремо, знайдіть та перегляньте теми, які включають його як посилання. Переконайтеся, що будь-які теми, які використовують окремий YAML, мають відповідну інформацію про версії. Якщо окремий YAML файл не посилається на жодні теми, розгляньте можливість його видалення замість оновлення.

Наприклад, якщо ви пишете навчальний посібник, що стосується версії Kubernetes 1.8, front matter вашого markdown файлу мають виглядати приблизно так:

---
title: <ваша назва навчального посібника>
min-kubernetes-server-version: v1.8
---

У прикладах коду та конфігурацій не включайте коментарі про альтернативні версії. Будьте обережні, щоб не включати некоректні твердження у ваші приклади у вигляді коментарів, наприклад:

apiVersion: v1 # попередні версії використовують...
kind: Pod
...

Словник Kubernetes.io

Список специфічних для Kubernetes термінів і слів, які слід використовувати послідовно у всьому сайті.

Shortcodes

Hugo Shortcodes допомагають створювати різні рівні риторичної привабливості. Наша документація підтримує три різні Shortcodes в цій категорії: Note {{< note >}}, Caution {{< caution >}} і Warning {{< warning >}}.

1. Оточуйте текст відкриваючим та закриваючим Shortcodeʼом.

2. Використовуйте наступний синтаксис для застосування стилю:

   {{< note >}}
   Немає необхідності включати префікс; Shortcode автоматично додає його. (Note:, Caution:, тощо)
   {{< /note >}}
   

   Вихідний результат:

   Примітка:

   Обраний префікс збігається з текстом теґа.

Note

Використовуйте {{< note >}} для виділення поради або корисної інформації.

Наприклад:

{{< note >}}
Ви _все ще_ можете використовувати Markdown всередині цих Shortcodeʼів.
{{< /note >}}

Вихідний результат:

Ви можете використовувати {{< note >}} у списку:

1. Використовуйте Shortcode примітки у списку

1. Другий пункт з вбудованою приміткою

   {{< note >}}
   Shortcode Warning, Caution і Note, вбудовані у списки, повинні мати відповідний відступ (на рівні початку тексту списку). Див. [Поширені проблеми з Shortcode](#common-shortcode-issues).
   {{< /note >}}

1. Третій пункт у списку

1. Четвертий пункт у списку

Вихідний результат:

1. Використовуйте Shortcode примітки у списку

2. Другий пункт з вбудованою приміткою

   Примітка:

   Шорткоди Warning, Caution і Note, вбудовані у списки, повинні мати відповідний відступ (на рівні початку тексту списку). Див. Поширені проблеми з Shortcode.

3. Третій пункт у списку

4. Четвертий пункт у списку

Caution

Використовуйте {{< caution >}} для привернення уваги до важливої інформації, щоб уникнути помилок.

Наприклад:

{{< caution >}}
Стиль виклику застосовується лише до рядка теґа вище безпосередньо.
{{< /caution >}}

Вихідний результат:

Warning

Використовуйте {{< warning >}} для вказівки на небезпеку або важливу інформацію, яку потрібно обовʼязково враховувати.

Наприклад:

{{< warning >}}
Будьте обережні.
{{< /warning >}}

Вихідний результат:

Поширені проблеми з Shortcode

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

Shortcode переривають нумеровані списки, якщо не зробити відступ у на рівні початку тексту списку перед сповіщенням та теґом.

Наприклад:

1. Розігрійте духовку до 350˚F

1. Приготуйте тісто та вилийте його у форму.
   {{< note >}}Змастіть форму для кращих результатів.{{< /note >}}

1. Випікайте 20-25 хвилин або до готовності.

Вихідний результат:

1. Розігрійте духовку до 350˚F

2. Приготуйте тісто та вилийте його у форму.

   Примітка:

   Змастіть форму для кращих результатів.

3. Випікайте 20-25 хвилин або до готовності.

Вирази Include

Shortcode всередині include statements зламають збірку. Необхідно вставити їх у батьківський документ до і після виклику include. Наприклад:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Елементи Markdown

Переноси рядків

Використовуйте один символ переносу рядка (\n) для розділення контенту на рівні блоків, таких як заголовки, списки, зображення, блоки коду тощо. Винятком є заголовки другого рівня, де необхідно зробити два переноси рядка. Заголовки другого рівня слідують після заголовків першого рівня (або заголовка) без передуючих абзаців або тексту. Два переноси рядка допомагають краще візуалізувати загальну структуру контенту в текстовому редакторі.

Ручне перенесення абзаців у вихідному коді Markdown є доречним, оскільки інструмент git та сайт GitHub генерують порівняння файлів на основі рядків. Ручне перенесення довгих рядків допомагає рецензентам легко знаходити зміни у PR і надавати зворотний звʼязок. Це також допомагає командам, які займаються локалізацією, відслідковувати зміни на рівні рядків¹. Перенесення рядка може відбуватися в кінці речення або після знака пунктуації. Винятком є випадки, коли Markdown-посилання або шорткод очікується в одному рядку.

Заголовки та назви

Користувачі цієї документації можуть використовувати інструменти озвучування тексту (екранний зчитувач) або іншу допоміжну технологію (AT). Екранні зчитувачі є лінійними вихідними пристроями, що виводять елементи на сторінку по одному. Якщо на сторінці багато контенту, ви можете використовувати заголовки для створення внутрішньої структури сторінки. Гарна структура сторінки допомагає всім користувачам легко орієнтуватися на сторінці або фільтрувати теми, які їх цікавлять.

Абзаци

Посилання

Списки

Групуйте елементи в списках, які повʼязані між собою і повинні зʼявлятися у певному порядку або для позначення кореляції між кількома елементами. Коли екранний зчитувач натрапляє на список, незалежно від того, чи це упорядкований або неупорядкований список, він оголошує користувачеві, що є група елементів списку. Потім користувач може використовувати клавіші зі стрілками для переміщення між різними елементами списку.

• Закінчуйте кожен елемент у списку крапкою, якщо один або більше елементів у списку є завершеними реченнями. Для збереження послідовності зазвичай всі елементи або жоден з них мають бути завершеними реченнями.

  Примітка:

  Упорядковані списки, що є частиною незавершеного вступного речення, можуть бути написані з маленької літери і пунктуацією так, ніби кожен елемент є частиною вступного речення.

• Використовуйте цифру один з крапкою (1.) для упорядкованих списків.

• Використовуйте (+), (*), або (-) для неупорядкованих списків, але якийсь один з цих символів у одному тексті (уникайте їх змішування)

• Залишайте порожній рядок після кожного списку.

• Відступайте вкладені списки на відповідну кількість пробілів, так щоб сімвол початку елемента спіску був на рівні з початком тексту елемента вищого рівня (наприклад, ⋅⋅⋅).

• Елементи списку можуть складатися з кількох абзаців. Кожен наступний абзац у пункті списку повинен бути відступлений нарівень початку тексту елементу списку або один табулятор.

Таблиці

Семантична мета таблиці — це представлення табличних даних. Користувачі з гарним зором можуть швидко сканувати таблицю, але екранний зчитувач проходить її рядок за рядком. Підпис таблиці використовується для створення описового заголовка для таблиці даних. Допоміжні технології (AT) використовують елемент підпису HTML для таблиці, щоб ідентифікувати вміст таблиці користувачеві в межах структури сторінки.

• Додавайте підписи до таблиць за допомогою shortcodes Hugo для таблиць.

Рекомендації щодо створення контенту

Цей розділ містить рекомендації для створення чіткого, лаконічного і послідовного контенту.

Використовуйте теперішній час

Виняток: Використовуйте майбутній або минулий час, якщо це необхідно для передачі правильного значення.

Використовуйте активний стан

Виняток: Використовуйте пасивний стан, якщо активний стан призводить до незручної конструкції.

Використовуйте просту і пряму мову

Використовуйте просту і пряму мову. Уникайте використання зайвих фраз, наприклад, слова "будь ласка".

Звертайтесь до читача на "ви"

Уникайте латинських фраз

Віддавайте перевагу англійським (місцевим) термінам замість латинських абревіатур.

Виняток: Використовуйте "etc." (et cetera) для позначення "та інше".

Шаблони, яких слід уникати

Уникайте використання "ми"

Використання "ми" у реченні може бути заплутаним, оскільки читач може не знати, чи є він частиною "ми", про яке ви говорите.

Уникайте жаргону та ідіом

Для багатьох читачів англійська є другою мовою. Уникайте жаргону та ідіом, щоб допомогти їм краще зрозуміти тему.

Уникайте тверджень про майбутнє

Уникайте обіцянок або натяків на майбутнє. Якщо вам потрібно говорити про функцію в альфа-версії, розмістіть текст під заголовком, який позначає його як альфа-інформацію.

Винятком з цього правила є документація про оголошені застарівання функцій, які плануються до видалення в майбутніх версіях. Один з прикладів такої документації — Посібник з міграції із застарілих API.

Уникайте тверджень, які незабаром стануть неактуальними

Уникайте слів таких як "зараз" і "новий". Функція, яка є новою сьогодні, може не вважатися новою через кілька місяців.

Уникайте слів, що припускають певний рівень розуміння

Уникайте слів таких як "просто", "легко", "зрозуміло". Ці слова не додають цінності.

Файл EditorConfig

Проєкт Kubernetes підтримує файл EditorConfig, який встановлює загальні стилістичні уподобання в текстових редакторах, таких як VS Code. Ви можете використовувати цей файл, якщо хочете переконатися, що ваші внески відповідають решті проєкту. Щоб переглянути файл, зверніться до .editorconfig в кореневій теці репозиторію.

Що далі

• Дізнайтеся про написання нової теми.
• Дізнайтеся про використання шаблонів сторінок.
• Дізнайтеся про власні hugo shortcodes.
• Дізнайтеся про створення pull request.