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

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

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

Язык

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

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

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

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

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

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

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

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

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

1. Отобразить информацию о Pod:

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

   Если пространство имён пода равняется default, вы можете опустить параметр '-n'.

Используйте полужирное начертание для элементов пользовательского интерфейса

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

Оформляйте как код имена файлов, директории и пути

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

Форматирование с использованием однострочного кода

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

Для однострочного (встроенного) блока кода в HTML-документе используйте тег <code>. В файле Markdown используйте обратную кавычку (`).

Имена полей объектов и пространства имён оформляйте как код

Имена компонентов и командного инструмента оформляйте как код

Начинайте предложение с имени инструмента или компонента

Используйте общее описание вместо имени компонента

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

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

Форматирование фрагментов кода

Не добавляйте символ приглашения командной строки

Отделяйте команды от вывода

Убедитесь, что 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 терминов и слов, которые будут регулярно встречаться по всему сайту.

Макрокоды

Макрокоды Hugo помогают создавать разного рода обращений к читателю. Наша документация поддерживает три разных макрокода для этого: примечание {{< note >}}, предостережение {{< caution >}} и предупреждение {{< warning >}}.

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

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

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

Результат:

Примечание

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

Например:

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

Результат:

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

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

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

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

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

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

Результат:

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

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

   Примечание:

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

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

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

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

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

Например:

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

Результат:

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

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

Например:

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

Результат:

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

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

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

Например:

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). Программы чтения с экрана — устройства вывода, которые выводят элементы на странице по очереди. Если на странице много текста, вы можете использовать заголовки, чтобы придать странице внутреннюю структуру. Хорошая структура страницы помогает всем читателям легко перемещаться по странице или выбрать интересующие темы.

Параграфы

Ссылки

Списки

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

• Заканчивайте каждый элемент в списке точкой, если один или несколько элементов в списке являются законченными предложениями. Как правило, для согласованности либо все элементы должны быть целыми предложениями, либо ни один из них.

  Примечание:

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

• Используйте цифру один (1.) для упорядоченных списков.

• Используйте (+), (*) или (-) для неупорядоченных списков.

• Добавьте пустую строку после каждого списка.

• Во вложенных списках добавьте отступ в четыре пробела (например, ⋅⋅⋅⋅).

• Элементы списка могут содержать несколько абзацев. Каждый последующий абзац в элементе списка должен иметь отступ в четыре пробела или один символ табуляции.

Таблицы

Семантическая цель таблицы данных состоит в представлении данных в табличном виде. Пользователи с нормальным зрением могут бегло просмотреть таблицу, однако программа для чтения с экрана сканирует таблицу построчно. Заголовок таблицы используется для создания информативного заголовка для табличных данных. Инструменты вспомогательных технологий (Assistive technologies, AT) используют элемент заголовка HTML-таблицы, чтобы идентифицировать для пользователей, какие на странице есть таблицы.

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

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

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

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

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

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

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

Используйте простой и понятный язык

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

Обращайтесь к читателю на "вы"

Избегайте использования латинских фраз

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

Исключение: используйте "etc." вместо "et cetera".

Ошибки, которые следует избегать

Избегайте использования "мы"

Использование "мы" в предложении может сбить с толку, так так неясно, кто под этим "мы" подразумевается (имеется ли в виду сам читатель при этом).

Избегайте жаргона и идиомы

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

Избегайте выражений о будущем

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

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

Избегайте таких слов, как "в настоящее время" и "новый". Новая функциональность в настоящее время не будет таковой через несколько месяцев.

Что дальше

• Подробнее про написание новой темы.
• Подробнее про использование шаблонов страниц.
• Подробнее про создание пулреквеста).