Edit This Page

Руководство по оформлению документации

На этой странице вы найдёте рекомендации по оформлению написания документации Kubernetes. Это рекомендации, а не правила. Используйте здравый смысл и не стесняйтесь предлагать изменения в этот документ в виде пулреквеста.

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

Заметка: В документации Kubernetes используется Blackfriday Markdown Renderer вместе с несколькими макрокодами Hugo для добавления поддержки записей глоссария, вкладок и отображения состояний функциональностей.

Язык

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

Процесс локализации документации на другие языки описан в соответствующей странице по локализации.

Правила форматирования документации

Используйте верблюжью нотацию для написания объектов API

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

Не разделяйте имя объекта API на отдельные слова. Например, пишите PodTemplateList, а не Pod Template List.

Указывая имена API-объектов, не добавляйте к ним слово "объект", за исключением случаев, когда это только ухудшает читаемость.

Можно делать и нельзя - Объекты API
Можно Нельзя
В Pod два контейнера. В поде два контейнера.
Deployment отвечает за ... Объект Deployment отвечает за ...
PodList — это список Pod. Pod List — это список подов.
Два ContainerPorts ... Два объекта ContainerPort ...
Два объекта ContainerStateTerminated ... Два ContainerStateTerminated ...

Используйте угловые скобки для заполнителей

Используйте угловые скобки для заполнителей. Сообщите читателю, что означает заполнитель.

  1. Отобразить информацию о 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 используйте обратную кавычку (`).

Можно делать и нельзя - Use code style for inline code and commands
Можно Нельзя
Команда 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.

Cтроковые и целочисленные значения полей пишите в обычном стиле

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

Можно делать и нельзя - Cтроковые и целочисленные значения полей пишите в обычном стиле
Можно Нельзя
Задайте значение для поля 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

Примеры кода и примеры конфигурации, которые включают информацию о версии, должны согласовываться с относящемуся к нему тексту.

Если информация зависит от версии, необходимо определить версию 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.io

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

Словарь Kubernetes.io
Термин Пример использования
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 >}}.

  1. Заключите текст в открывающий и закрывающий макрокод.

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

    {{< note >}}
Вам не нужно указывать надпись; макрокод автоматически добавит её. (Примечание:, Предостережение:, и т.д.)
{{< /note >}}

Результат:

Заметка: Надпись блока будет такой же, как и имя тега.

Примечание

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

Например:

{{< note >}}
Вы _также_ можете использовать Markdown внутри этих выносок.
{{< /note >}}

Результат:

Заметка: Вы также можете использовать Markdown внутри этих выносок.

Вы можете использовать {{< note >}} в списке:

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

1. Второй пункт с добавленным блоком примечания

   {{< note >}}
   Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел [Распространённые проблемы с шорткодами](#распространённые-проблемы-с-шорткодами).
   {{< /note >}}

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

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

Результат:

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

  2. Второй пункт с добавленным блоком примечания

    Заметка: Макрокоды предупреждения, предостережения и примечания, добавленные в списки, должны содержать отступ в четыре пробела. Смотрите раздел Распространённые проблемы с шорткодами.

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

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

Предостережение

Используйте {{< caution >}}, чтобы обратить внимание к важной информации, которая поможет избежать подводных камней.

Например:

{{< caution >}}
Оформление выноски применяется только к строке, следующей после тега выше.
{{< /caution >}}

Результат:

Внимание: Оформление выноски применяется только к строке, следующей после тега выше.

Предупреждение

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

Например:

{{< warning >}}
Острожно.
{{< /warning >}}

Результат:

Предупреждение: Острожно.

Встраиваемая среда выполнения Katacoda

С помощью этой кнопки пользователи могут запустить Minikube в своём браузере с помощью терминала Katacoda. Таким образом снижается порог входа, позволяя пользователям попробовать Minikube с помощью одного щелчка мыши, вместо того, чтобы устанавливать Minikube и Kubectl локально.

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

Внимание: Сессия ограничена 15 минутами.

Например:

{{< kat-button >}}

Результат:

Распространённые проблемы с шорткодами

Упорядоченные списки

Макрокоды сбросят нумерацию в нумерованных списках, если вы не добавите отступ в четыре пробела перед уведомлением и тегом.

Например:

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

1. Подготовить тесто и вылить её в формочку для выпечки.
   {{< note >}}Для лучшего результата смажьте формочку.{{< /note >}}

1. Выпекать 20-25 minutes или пока тесто не зарумянится.

Результат:

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

  2. Подготовить тесто и вылить её в формочку для выпечки.

    Заметка: Для лучшего результата смажьте формочку.

  3. Выпекать 20-25 minutes или пока тесто не зарумянится.

Выражения для вставок

Макрокоды внутри include-выражений нарушит процесс сборки. Поэтому они должны быть вставлены в родительский документ до и после вызова include. Например:

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

Элементы Markdown

Переносы строк

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

Заголовки

Люди, просматривающие документацию, могут использовать программу чтения с экрана или другую вспомогательную технологию (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-таблицы, чтобы идентифицировать для пользователей, какие на странице есть таблицы.

  • Добавьте подписи к таблицам с помощью соответствующих макрокодов Hugo.

Рекомендации по написанию контента

В этом разделе перечислены рекомендации для написания ясного, лаконичного и единообразного текста документации.

Используйте настоящее время

Можно делать и нельзя - Используйте настоящее время
Можно Нельзя
Эта команда запускает прокси. Эта команда запустит прокси.

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

Используйте действительный залог

Можно делать и нельзя - Используйте действительный залог
Можно Нельзя
Вы можете изучить 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 предоставляет ...

Что дальше