Руководство DigitalOcean по техническому письму

DigitalOcean с нетерпением ждет продолжения создания своей коллекции технических статей, связанных с администрированием серверов и разработкой программного обеспечения. Чтобы обеспечить постоянное качество и стиль статей DigitalOcean, мы разработали следующие рекомендации.

В этом руководстве есть три раздела:

Style, наш высокоуровневый подход к написанию технических руководств
Structure, объяснение нашего макета и содержания
Formatting and Terminology, ссылка на Markdown и терминологию

Чтобы быстро публиковаться, авторам сообщества DigitalOcean следует полностью прочитать разделы о стиле и структуре. Нашиtemplates полезны в качестве отправной точки для статьи, а раздел о форматировании этого руководства вместе с нашимиMarkdown previewer можно использовать в качестве ссылок при написании. У нас также естьtechnical best practices guide для наших технических рекомендаций.

Стиль

Статьи DigitalOcean должны быть:

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

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

Мы явно включаем каждую команду, которую читатель должен пройти от своего первого SSH-соединения на новом сервере до окончательной рабочей настройки. Мы также предоставляем читателям все объяснения и справочную информацию, необходимую для понимания учебника. Наша цель - научить наших читателей, а не просто копировать и вставлять.

Технически подробный и правильный

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

Практичный, полезный и автономный

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

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

Дружелюбный, но формальный

Наши уроки направлены на дружелюбный, но формальный тон. Это означает, что статьи не включают жаргон, мемы или чрезмерные шутки. Это также означает, что, в отличие от постов в блоге, мы не используем первое лицо единственного числа (например, "Думаю …"). Вместо этого мы используем множественное число от первого лица (например, «Мы установим ...) или второго человека (например, «Вы настроите…»).

Состав

Уроки DigitalOcean имеют последовательную структуру, состоящую из следующих разделов:

заглавие
Вступление
Цели (необязательно)
Предпосылки
Шаг 1 - Делаем первое
Шаг 2 - Делаем следующее
…
Шаг n - Делать последнее
Заключение

У нашихarticle templates есть этот макет в Markdown, который вы можете использовать в качестве отправной точки для своих собственных статей. Formatting section of this guide содержит более подробную информацию о наших соглашениях о форматировании.

заглавие

Типичный заголовок имеет следующий формат:How To <Accomplish a Task> with <Software> on <Distro>.

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

Например, если ваше руководство посвящено установке Caddy, скорее всего, цель будетhost a website. Если ваше руководство посвящено установке FreeIPA, целью может бытьset up centralized Linux authentication. Названия, которые включают цель (например, «https://www.digitalocean.com/community/tutorials/how-to-create-a-status-page-with-cachet-on-debian-8[How для создания страницы состояния с Cachet в Debian 8] »), как правило, более информативны для читателя, чем заголовки, которые этого не делают (например,« Как установить и настроить Cachet в Debian 8 »).

Введение и цели

Первый раздел каждого учебника - этоIntroduction, который обычно занимает от 1 до 3 абзацев.
Цель введения - ответить читателю на следующие вопросы:

Какова цель учебника? Что добьется читатель, если последует за ним?
Какое программное обеспечение задействовано и что делает каждый компонент (кратко)?
Каковы преимущества использования этого конкретного программного обеспечения в этой конфигурации? Каковы практические причины, по которым читатель должен следовать этому руководству?

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

Вот несколько хороших примеров:this Prometheus tutorial’s introduction иthis Pydio tutorial’s goals.

Предпосылки

РазделыPrerequisites обучающих программ DigitalOcean имеют очень конкретный формат и цели.

Цель состоит в том, чтобы объяснитьexactly, что читатель должен иметь или делать, прежде чем следовать текущему руководству. Формат представляет собой маркированный список, который читатель может использовать в качестве контрольного списка. Каждый пункт должен содержать ссылку на существующий учебник DigitalOcean, который охватывает необходимый контент. Это позволяет вам полагаться на существующий контент, который работает, а не начинать с нуля.

Общие обязательные пункты включают в себя:

Количество необходимых серверов, включая распределение, первоначальную настройку сервера и любые дополнительные необходимые параметры (например, требования к памяти, ключи API DO, IPv6 или частные сети).
Установка и настройка программного обеспечения.
Обязательные настройки DNS или SSL-сертификаты.
Дополнительные учетные записи пользователей, такие как GitHub, Facebook, Twitter или другие службы, которые понадобятся вашему читателю.

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

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

Вы можете увидеть примеры хороших предпосылок для:

Серверы Ubuntu 16.04, установка программного обеспечения и записи DNS вthis Minio tutorial’s prerequisites.
Серверы CentOS 7 и записи DNS вthis FreeIPA tutorial’s prerequisites.
Серверы Debian 8 с требованиями к памяти и настройкой программного обеспечения с использованием частичных шагов из других руководств вthis Cachet tutorial’s prerequisites.
Обработка нескольких серверов с установкой программного обеспечения вthis Nagios and Alerta tutorial’s prerequisites.

меры

РазделыStep - это части вашего учебника, в которых вы описываете, что нужно сделать читателю.

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

Все команды в шаге должны быть в отдельной строке в своем блоке кода, и каждой команде должно предшествовать описание. Аналогично, всегда вводите файл или сценарий, описывая его общее назначение, а затем объясните любые изменения, которые читатель будет вносить в файл. Без этих объяснений читатели не смогут настраивать, обновлять или устранять неполадки своего сервера в долгосрочной перспективе.

custom Markdown and formatting guidelines от DigitalOcean призваны помочь сделать инструкции наших руководств максимально удобными для чтения. This Docker Swarm tutorial - хороший пример того, как использовать наш собственный Markdown, чтобы различать команды, выполняемые на нескольких разных серверах, а также локально.

Заключение

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

Вот несколько хороших примеров:this LXD tutorial’s conclusion, https: //www.digitalocean.com/community/tutorials/how-to-monitor-cpu-use-on-digitalocean-droplets#conclusion [заключение этого руководства по мониторингу ЦП] и this Mosquitto tutorial’s conclusion.

форматирование

Уроки DigitalOcean отформатированы на языке разметки Markdown. Daring Fireball публикует подробное руководство по Markdown, если вы с ним не знакомы. DigitalOcean также использует несколькоcustom Markdown. Примеры наших пользовательских Markdown находятся в соответствующих разделах ниже.

Заголовки

Каждый раздел наших руководств имеет соответствующий заголовок: заголовок должен быть заголовком H1; введение должно быть заголовком H3; цели, предпосылки, шаги и выводы должны иметь заголовки H2. Вы можете увидеть этот формат в нашемMarkdown article templates.

Для процедурных руководств заголовки шагов должны включать номера шагов (числовые), за которыми следует длинное тире (—). Заголовки шагов также должны использовать герундий, то есть слова-ing. Пример заголовка шага -Step 1 — Installing Nginx.

Используйте заголовки H3 экономно и избегайте заголовков H4. Если вам нужно использовать подзаголовки, убедитесь, что в этом разделе учебника есть два или более заголовка этого уровня. В качестве альтернативы рассмотрите возможность сделать несколько шагов вместо этого.

Форматирование на уровне строк

Bold text следует использовать для:

Видимый текст GUI
Имена хостов и пользователей, напримерwordpress-1 илиsammy
Списки терминов
Акцент при изменении контекста для команды, такой как переключение на новый сервер или пользователя

Italics следует использовать только при введении технических терминов. Например, сервер Nginx будет нашимload balancer.

Встроенное форматирование кода должно использоваться для:

Имена команд, напримерunzip
Имена пакетов, напримерmysql-server
Дополнительные команды
Имена файлов и пути, например~/.ssh/authorized_keys
Примеры URL, напримерhttp://your_domain
Порты, например:3000
Нажатия клавиш, которые должны быть ЗАГЛАВНЫМИ БУКВАМИ и использовать символ плюса **, если клавиши необходимо нажимать одновременно, например, `+ ENTER` илиCTRL+C

Кодовые блоки

Блоки кода должны использоваться для:

Команды, которые читатель должен выполнить, чтобы завершить урок
Файлы и скрипты
Терминальный выход
Интерактивные диалоги в тексте

Выдержки и пропуски в файлах могут быть обозначены многоточием (…). Если большую часть файла можно оставить с настройками по умолчанию, обычно лучше показать только тот раздел, который необходимо изменить.

Префиксы блоков кода

Не включайте командную строку в блок кода. Вместо этого используйте пользовательскую разметку DigitalOcean для пользовательских команд без полномочий root, пользовательских команд пользователя и пользовательских префиксов соответственно:

```command
sudo apt-get update
```

```super_user
adduser sammy
```

```custom_prefix(mysql>)
FLUSH PRIVILEGES;
```

Вот как выглядят предыдущие примеры при визуализации:

sudo apt-get update

adduser sammy

FLUSH PRIVILEGES;

Метки кодовых блоков

DigitalOcean Markdown также включает метки и вторичные метки. Вы можете добавлять метки к блокам кода, добавляя строку с[label Label text] или[secondary_label Secondary label text] в любом месте блока.

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

Этикетки выглядят следующим образом:

Это текст метки

This is one line of the file
This is another line of the file
. . .
This is a line further down the file

Пример вторичной метки:

This is the secondary label textThis is some output from a command

Цвета среды блока кода

Markdown DigitalOcean позволяет вам раскрасить фон блока кода, добавив строку с[environment name] в любом месте блока. Варианты дляname:local,second,third,fourth иfifth.

Это пример команды локального сервера:

ssh root@your_server_ip

Это не первичные примеры команд сервера, полезные для многосерверных настроек:

echo "Secondary server"

echo "Third server"

echo "Fourth server"

echo "Fifth server

Примечания и предупреждения

Парсер DigitalOcean Markdown позволяет использовать настраиваемые блоки кодаnote иwarning для отображения очень важного текста.

Вот пример Markdown для заметки и предупреждения (это изображение):

Notes and Warnings

Вот результат:

[.note] #Note: Это примечание.
#

[.warning] #Warning: Это предупреждение.
#

переменные

Выделите все элементы, которые должны быть изменены читателем, например, примеры URL или измененные строки в файлах конфигурации. Вы можете сделать это, окружив слово или строку нашей специальной разметкой<^>. Обратите внимание, что вы не можете выделить несколько строк одной парой символов, поэтому вам нужно выделить каждую строку отдельно.

Если вы ссылаетесь на переменную в контексте, где вы обычно также используете форматированиеin-line code, вы должны использоватьboth styles. Убедитесь, что ваш учебник максимально доступен, используя язык, как «выделено в предыдущем блоке кода» вместо «выделено красным выше».

Избегайте таких слов, как «выделено красным ниже»

Изображения и другие активы

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

Если вы включаете изображения в свой учебник, пожалуйста, следуйте этим рекомендациям:

Включите описательный альтернативный текст, чтобы читатели, использующие программу чтения с экрана, могли полагаться на альтернативный текст, а не на изображение.
Используйте формат файла.png
Образы хоста наimgur
Сделайте изображение с максимально короткой высотой

Если вы создадите макет диаграммы для своего урока, мы создадим диаграмму в стиле DigitalOcean. Мы также загрузим все изображения на серверы DigitalOcean во время публикации.

Вот пример Markdown для включения изображений в ваш урок:

![Alt text for screen readers](http://imgur.com/your_image_url)

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

терминология

Пользователи, имена хостов и домены

Наш пример имени пользователя по умолчанию -sammy. Вы также можете выбрать что-нибудь описательное, если это полезно, напримерwebdav-kai илиnsd.

your_server - имя хоста по умолчанию, хотя вам рекомендуется выбрать что-нибудь описательное, особенно в многосерверных настройках, напримерdjango_replica_1.

your_domain - домен по умолчанию. Для настройки нескольких серверов вы можете выбрать что-то вродеprimary-1.your_domain илиreplica-1.your_domain. В то время какexample.com является допустимым доменом для документации, использованиеyour_domain в учебниках делает более понятным, что читатель должен изменить домен в примерах.

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

пример файла конфигурации

ip: your_server_ip
domain: primary-1.your_domain

Это дает понять читателям, что они должны что-то изменить.

IP-адреса и URL

your_server_ip со встроенным форматированием кода и выделением переменных - это способ по умолчанию для отображения IP-адреса. Вы можете отображать несколько IP-адресов с такими именами, какprimary_private_ip иreplica_private_ip. Если вам нужно проиллюстрировать более реалистичные IP-адреса, используйте адрес вone of the two blocks reserved for documentation as per RFC-5737. В частности, мы рекомендуем203.0.113.0/24 для публичных адресов и198.51.100.0/24 для частных адресов.

Примеры URL, которые содержат переменную, которую читатель должен настроить, должны использовать форматирование кода с выделенной переменной. По умолчанию мы используемyour_domain. напримерhttps://your_domain:3000/simple/ илиhttp://your_server_ip/. Тем не менее, живые ссылки должны вместо этого использовать стандартный стиль ссылок Markdown без дополнительного форматирования.

Программного обеспечения

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

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

Многосерверные установки

Для технической ясности используйте терминологию проекта для многосерверных настроек. Пожалуйста, будьте уверены, что условия исходят от проекта. Например: «В проекте Django исходный сервер называетсяprimary, а вторичный сервер -replica. В проекте MySQL исходный сервер называетсяmaster, а вторичный сервер -slave ».

При более абстрактном обсуждении многосерверных архитектур используйте терминыprimary иreplica илиmanager иworker.

Технические передовые практики

В нашем руководствеtechnical best practices guide есть дополнительные рекомендации, которые помогут вам создавать последовательные и качественные учебные пособия, которые помогут нашим читателям.

Перейдите по этой ссылке наbecome a DigitalOcean author.

TOC