На этой странице вы найдёте рекомендации по оформлению написания документации Kubernetes. Это рекомендации, а не правила. Используйте здравый смысл и не стесняйтесь предлагать изменения в этот документ в виде пулреквеста.
Для получения подробной информации о создании нового контента в документацию Kubernetes посмотрите руководство по контенту документации, а также следуйте инструкциям по использованию шаблонов страниц и открытию пулревеста в документацию.
Заметка: В документации Kubernetes используется Blackfriday Markdown Renderer вместе с несколькими макрокодами Hugo для добавления поддержки записей глоссария, вкладок и отображения состояний функциональностей.
Документация Kubernetes была переведена на несколько языков (см. README-файлы локализаций).
Процесс локализации документации на другие языки описан в соответствующей странице по локализации.
Когда вы указываете имя API-объекта, используйте те же самые прописные и строчные буквы так, как они записаны в имени объекта. Как правило, имена объектов API написаны с использованием верблюжьей нотации.
Не разделяйте имя объекта API на отдельные слова. Например, пишите PodTemplateList, а не Pod Template List.
Указывая имена API-объектов, не добавляйте к ним слово “объект”, за исключением случаев, когда это только ухудшает читаемость.
Можно | Нельзя |
---|---|
В Pod два контейнера. | В поде два контейнера. |
Deployment отвечает за … | Объект Deployment отвечает за … |
PodList — это список Pod. | Pod List — это список подов. |
Два ContainerPorts … | Два объекта ContainerPort … |
Два объекта ContainerStateTerminated … | Два ContainerStateTerminated … |
Используйте угловые скобки для заполнителей. Сообщите читателю, что означает заполнитель.
Отобразить информацию о Pod:
kubectl describe pod <pod-name> -n <namespace>
Если пространство имён пода равняется default
, вы можете опустить параметр ‘-n’.
Можно | Нельзя |
---|---|
Нажмите на Fork. | Нажмите на “Fork”. |
Выберите Other. | Выберите “Other”. |
Можно | Нельзя |
---|---|
Кластер — это набор узлов … | “Кластер” — это набор узлов … |
Эти компоненты формируют плоскость управления. | Эти компоненты формируют плоскость управления. |
Можно | Нельзя |
---|---|
Откройте файл envars.yaml . |
Откройте файл envars.yaml. |
Перейдите в директорию /docs/tutorials . |
Перейдите в директорию /docs/tutorials. |
Откройте файл /_data/concepts.yaml file. |
Откройте файл /_data/concepts.yaml. |
Можно | Нельзя |
---|---|
события записываются с соответствующей “стадией”. | события записываются с соответствующей “стадией.” |
Копия называется “fork”. | Копия называется “fork.” |
Для однострочного (встроенного) блока кода в HTML-документе используйте тег <code>
. В файле Markdown используйте обратную кавычку (`).
Можно | Нельзя |
---|---|
Команда kubectl run создает Deployment. |
Команда “kubectl run” создает Deployment. |
Для декларативного управления используйте kubectl apply . |
Для декларативного управления используйте “kubectl apply”. |
Заключите примеры кода в тройные обратные кавычки. ( `) |
Заключите примеры кода с использованием любого другого синтаксиса. |
Используйте одинарные обратные кавычки для выделения встроенного кода. Например, var example = true . |
Используйте две звездочки (**) или подчёркивание (_) для выделения встроенного кода. Например, var example = true. |
Используйте тройные обратные кавычки до и после многострочного блока кода для отдельных блоков кода. | Используйте многострочные блоки кода для создания диаграмм, блок-схем или т.д. |
Используйте понятные имена переменных с соответствующим контекстом. | Используйте имена переменных, такие как ‘foo’, ‘bar’ и ‘baz’, которые не имеют смысла и которым не хватает контекста. |
Удаляйте завершающие пробелы в коде. | Добавляйте конечные пробелы в код там, где они необходимо, поскольку программа для чтения с экрана также будет зачитывать пробелы. |
Заметка: На сайте включена подсветка синтаксиса для примеров кода, хотя указывать язык необязательно. Подсветка синтаксиса в блоке кода должна соответствовать рекомендациям по контрастности.
Можно | Нельзя |
---|---|
Задайте значение для поля replicas в конфигурационном файле. |
Задайте значение для поля “replicas” в конфигурационном файле. |
Значением поля exec является объект ExecAction. |
Значением поля “exec” является объект ExecAction. |
Запустите процесс как Daemonset в пространстве имен kube-system . |
Запустите процесс как Daemonset в пространстве имен kube-system. |
Можно | Нельзя |
---|---|
kubelet сохраняет стабильность узла. | kubelet сохраняет стабильность узла. |
kubectl обрабатывает поиск и аутентификацию на сервере API. |
kubectl обрабатывает поиск и аутентификацию на apiserver. |
Запустите процесс с использованием сертификата kube-apiserver --client-ca-file=FILENAME . |
Запустите процесс с использованием сертификата kube-apiserver –client-ca-file=FILENAME. |
Можно | Нельзя |
---|---|
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. |
Можно | Нельзя |
---|---|
Сервер Kubernetes API следует спецификации OpenAPI. | apiserver следует спецификации OpenAPI. |
Агрегированные API-интерфейсы — вспомогательные API-серверы. | Агрегированные API-интерфейсы — вспомогательные APIServers. |
Для значений полей типа string или integer используйте обычный стиль без кавычек.
Можно | Нельзя |
---|---|
Задайте значение для поля imagePullPolicy как Always. |
Задайте значение для поля imagePullPolicy как “Always”. |
Задайте значение для поля image как nginx:1.8. |
Задайте значение для поляimage как nginx:1.8 . |
Задайте значение для поля replicas как 2. |
Задайте значение для поля replicas как 2 . |
Можно | Нельзя |
---|---|
kubectl get pods | $ kubectl get pods |
Убедитесь, что 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 в секции prerequisites
шаблона задачи или шаблона руководства. После сохранения страницы секция prerequisites
отобразится в отдельном блоке с заголовком Подготовка к работе.
Для указания версии Kubernetes для страницы задачи или руководства в фронтальную часть файла добавьте поле min-kubernetes-server-version
.
Если YAML-пример определён в отдельном файле, поищите и просмотрите темы, которые ссылаются на него. Убедитесь, что темы с подключённым YAML-файлом содержат соответствующую информацию о версии. Если ни одна из тем не использует какой-либо YAML-файл подумайте над тем, чтобы удалить его вместо того, чтобы обновления.
Например, если вы пишете руководство, предназначенное для использования с версией Kubernetes 1.8, фронтальная часть вашего Markdown-файла должен выглядеть примерно так:
---
title: <your tutorial title here>
min-kubernetes-server-version: v1.8
---
В примерах кода и конфигурации не добавляйте комментарии про альтернативные версии. Убедитесь в том, чтобы в комментариях ваших примеров не содержались некорректные сведения, такие как ниже:
apiVersion: v1 # в более ранних версиях...
kind: Pod
...
Список специфичных для Kubernetes терминов и слов, которые будут регулярно встречаться по всему сайту.
Термин | Пример использования |
---|---|
Kubernetes | Kubernetes всегда должен начинаться с заглавной буквы. |
Docker | Docker всегда должен начинаться с заглавной буквы. |
SIG Docs | SIG Docs, а не SIG-DOCS или другие варианты. |
On-premises | On-premises or On-prem rather than On-premise or other variations. |
Макрокоды Hugo помогают создавать разного рода обращений к читателю. Наша документация поддерживает три разных макрокода для этого: примечание {{< note >}}, предостережение {{< caution >}} и предупреждение {{< warning >}}.
Заключите текст в открывающий и закрывающий макрокод.
Используйте следующий синтаксис для определения стиля:
{{< note >}}
Вам не нужно указывать надпись; макрокод автоматически добавит её. (Примечание:, Предостережение:, и т.д.)
{{< /note >}}
Результат:
Заметка: Надпись блока будет такой же, как и имя тега.
Используйте {{< note >}} для выделения подсказки или части информации, которая может быть полезна для ознакомления.
Например:
{{< note >}}
Вы _также_ можете использовать Markdown внутри этих выносок.
{{< /note >}}
Результат:
Заметка: Вы также можете использовать Markdown внутри этих выносок.
Вы можете использовать {{< note >}} в списке:
1. Используйте макрокод примечания в списке
1. Второй пункт с добавленным блоком примечания
{{< note >}}
Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел [Распространённые проблемы с шорткодами](#распространённые-проблемы-с-шорткодами).
{{< /note >}}
1. Третий пункт в списке
1. Четвертый пункт в списке
Результат:
Используйте макрокод примечания в списке
Второй пункт с добавленным блоком примечания
Заметка: Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел Распространённые проблемы с шорткодами.
Третий пункт в списке
Четвертый пункт в списке
Используйте {{< caution >}}, чтобы обратить внимание к важной информации, которая поможет избежать подводных камней.
Например:
{{< caution >}}
Оформление выноски применяется только к строке, следующей после тега выше.
{{< /caution >}}
Результат:
Внимание: Оформление выноски применяется только к строке, следующей после тега выше.
Используйте {{< warning >}} для обозначения предупреждающей информации или такой, которую чрезвычайно важно соблюдать.
Например:
{{< warning >}}
Острожно.
{{< /warning >}}
Результат:
Предупреждение: Острожно.
С помощью этой кнопки пользователи могут запустить Minikube в своём браузере с помощью терминала Katacoda. Таким образом снижается порог входа, позволяя пользователям попробовать Minikube с помощью одного щелчка мыши, вместо того, чтобы устанавливать Minikube и Kubectl локально.
Встроенная среда выполнения сконфигурирована для выполнения команды minikube start
и позволяет пользователям пройти руководство в той же самой вкладке, что и документация.
Внимание: Сессия ограничена 15 минутами.
Например:
{{< kat-button >}}
Результат:
Макрокоды сбросят нумерацию в нумерованных списках, если вы не добавите отступ в четыре пробела перед уведомлением и тегом.
Например:
1. Разогреть духовку до 350˚F
1. Подготовить тесто и вылить её в формочку для выпечки.
{{< note >}}Для лучшего результата смажьте формочку.{{< /note >}}
1. Выпекать 20-25 minutes или пока тесто не зарумянится.
Результат:
Разогреть духовку до 350˚F
Подготовить тесто и вылить её в формочку для выпечки.
Заметка: Для лучшего результата смажьте формочку.
Выпекать 20-25 minutes или пока тесто не зарумянится.
Макрокоды внутри include-выражений нарушит процесс сборки. Поэтому они должны быть вставлены в родительский документ до и после вызова include. Например:
{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}
Добавляйте одну новую строку для разделения содержимого таких блоков, как заголовки, списки, изображения, многострочный код и т.д. Исключение составляют заголовки второго уровня, которые должны быть разделены двумя переводами строки. Заголовки второго уровня следуют за первым уровнем (или названием страницы). Две пустые строки помогает лучше наглядно представить общую структуру содержимого в редакторе кода.
Люди, просматривающие документацию, могут использовать программу чтения с экрана или другую вспомогательную технологию (Assistive technologies, AT). Программы чтения с экрана — устройства вывода, которые выводят элементы на странице по очереди. Если на странице много текста, вы можете использовать заголовки, чтобы придать странице внутреннюю структуру. Хорошая структура страницы помогает всем читателям легко перемещаться по странице или выбрать интересующие темы.
Можно | Нельзя |
---|---|
Обновите заголовок в фронтальной части страницы или записи блога. | Используйте заголовок первого уровня, так как Hugo автоматически преобразует название страницы в фронтальной части в заголовок первого уровня. |
Используйте упорядоченные заголовки, чтобы сформировать общее представление о содержании страницы. | Используйте заголовки с уровня 4 по 6, если только это только в этом нет необходимости. Если текст настолько подробный, возможно, его нужно разделить на отдельные статьи. |
Используйте знак решётки или хеша (#) для всех видов контента, кроме записей блога. | Используйте подчеркивание (— или ===) для обозначения заголовков первого уровня. |
Начинайте с большой буквы только первое слово в заголовке. Например, Расширение kubectl с помощью плагинов | Пишите с заглавной буквы все слова в заголовке. Например, Расширение Kubectl С Помощью Плагинов |
Можно | Нельзя |
---|---|
Проследите за тем, чтобы в одном абзаце было не более 6 предложений. | Добавить к первом абзацу отступ с пробелами. Например, ⋅⋅⋅Три пробела перед абзацем образуют отступ. |
Используйте три дефиса (—) для создания горизонтальной черты. Используйте горизонтальные линии для обозначения конца в содержании абзаца. Например, смена места в истории или переход темы в разделе. | Используйте горизонтальные линии для оформления. |
Можно | Нельзя |
---|---|
Указывайте ссылки, которые передают суть содержания, на который они ссылаются. Например: “Некоторые порты открыты на ваших машинах. Смотрите раздел Проверка необходимых портов, чтобы получить дополнительную информацию”. | Используйте двусмысленные термины, такие как “нажмите сюда”. Например: Некоторые порты открыты на ваших машинах. Смотрите этот раздел, чтобы получить дополнительную информацию”. |
Указывайте ссылки в стиле Markdown: [текст ссылки](URL) . Например: [Макрокоды Hugo](/docs/contribute/style/hugo-shortcodes/#table-captions) отобразится как Макрокоды Hugo. |
Указывайте ссылки в формате HTML: <a href="/media/examples/link-element-example.css" target="_blank">Ознакомьтесь с нашим руководством!</a> или добавляйте ссылки, которые открываются в новых вкладках или окнах. Например: [example website](https://example.com){target="_blank"} |
Сгруппируйте пункты в списке так, чтобы они были связаны друг с другом и следовали в определённом порядке, либо чтобы они сохраняли взаимосвязь между несколькими элементами. Когда программа чтения с экрана встречает нумерованный или неупорядоченный список, пользователю будет проинформирован, что существует группа из элементов списка. Затем пользователь может использовать клавиши-стрелки для перемещения между разными элементами в списке. Навигационные ссылки по сайту также могут быть помечены как элементы списка; в конечном счёте, все они просто группа связанных ссылок.
Заметка: Упорядоченные списки, которые являются частью неполного вступительного предложения, могут быть написаны в нижнем регистре и оканчиваться на точку, как если бы каждый элемент был составляющей вступительного предложения.
Используйте цифру один (1.) для упорядоченных списков.
Используйте (+), (*) или (-) для неупорядоченных списков.
Добавьте пустую строку после каждого списка.
Во вложенных списках добавьте отступ в четыре пробела (например, ⋅⋅⋅⋅).
Элементы списка могут содержать несколько абзацев. Каждый последующий абзац в элементе списка должен иметь отступ в четыре пробела или один символ табуляции.
Семантическая цель таблицы данных состоит в представлении данных в табличном виде. Пользователи с нормальным зрением могут бегло просмотреть таблицу, однако программа для чтения с экрана сканирует таблицу построчно. Заголовок таблицы используется для создания информативного заголовка для табличных данных. Инструменты вспомогательных технологий (Assistive technologies, AT) используют элемент заголовка HTML-таблицы, чтобы идентифицировать для пользователей, какие на странице есть таблицы.
В этом разделе перечислены рекомендации для написания ясного, лаконичного и единообразного текста документации.
Можно | Нельзя |
---|---|
Эта команда запускает прокси. | Эта команда запустит прокси. |
Исключение: используйте будущее или прошедшее время, если требуется передать правильный смысл.
Можно | Нельзя |
---|---|
Вы можете изучить API с помощью браузера. | API можно изучить с помощью браузера. |
В файле YAML определяется количество реплик. | Количество реплик определяется в файле YAML. |
Исключение: используйте страдательный залог, если в действительном залоге получается неудачная формулировка.
Используйте простой и доступный язык. Избегайте использования ненужных фраз, например, “пожалуйста”.
Можно | Нельзя |
---|---|
Чтобы создать ReplicaSet, … | Для того чтобы создать a ReplicaSet, … |
Смотрите конфигурационный файл. | Пожалуйста, смотрите конфигурационный файл. |
Посмотрите Pods. | С помощью следующей команды мы посмотрим Pods. |
Можно | Нельзя |
---|---|
Вы можете создать Deployment с помощью … | Мы создадим Deployment с помощью … |
В предыдущем выводе вы можете увидеть … | В предыдущем выводе мы можем увидеть … |
Вместо латинских аббревиатур используйте соответствующие выражения на английском.
Можно | Нельзя |
---|---|
For example, … | e.g., … |
That is, … | i.e., … |
Исключение: используйте “etc.” вместо “et cetera”.
Использование “мы” в предложении может сбить с толку, так так неясно, кто под этим “мы” подразумевается (имеется ли в виду сам читатель при этом).
Можно | Нельзя |
---|---|
Версия 1.4 включает в себя … | В версии 1.4 мы добавили … |
Kubernetes представляет новую возможность для … | Мы представляем новую возможность … |
На этой странице вы узнаете, как использовать Pods. | На этой странице мы познакомимся с Pods. |
Некоторые читатели говорят на английском как на втором языке. Избегайте жаргона и идиом, чтобы облегчить им понимание.
Можно | Нельзя |
---|---|
Internally, … | Under the hood, … |
Create a new cluster. | Turn up a new cluster. |
Не давайте обещаний или намеков на будущее. Если вам нужно рассказать про функциональность в альфа-версии, под соответствующем заголовком напишите поясняющий текст, что информация относится к альфа-версии.
Избегайте таких слов, как “в настоящее время” и “новый”. Новая функциональность в настоящее время не будет таковой через несколько месяцев.
Можно | Нельзя |
---|---|
В версии 1.4 … | В текущей версии … |
Функциональность Federation предоставляет … | Новая функциональность Federation предоставляет … |
Была ли эта страница полезной?
Спасибо за отзыв! Если у вас есть конкретный вопрос об использовании Kubernetes, спрашивайте Stack Overflow. Сообщите о проблеме в репозитории GitHub, если вы хотите сообщить о проблеме или предложить улучшение.