Поиск по сайту:

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


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

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

  • Стиль — наш высокоуровневый подход к написанию технических руководств.
  • Структура, объяснение нашего макета и содержания
  • Форматирование, справочное руководство по Markdown
  • Терминология, справочник по общеупотребительным терминам и словоупотреблению

Чтобы быстро опубликоваться, мы рекомендуем вам полностью прочитать разделы «Структура», прежде чем вы начнете работать над своей статьей.

Вы можете использовать руководство «Как написать предложение» и «Наброски для руководства сообщества DigitalOcean» в качестве справочных материалов при написании статьи.

У нас также есть руководство по передовым техническим методам, в котором изложены наши технические рекомендации.

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

Читайте дальше, чтобы узнать о стиле нашей статьи.

Стиль

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

  • Всеобъемлющий и написанный для всех уровней опыта
  • Технически подробно и правильно
  • Практично, полезно и автономно
  • Дружелюбный, но формальный

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

Всеобъемлющий и написанный для всех уровней опыта

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

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

Мы избегаем таких слов, как «просто», «прямолинейно», «легко», «просто», «очевидно» и «справедливо», поскольку эти слова делают предположения о знаниях читателя. Хотя авторы используют эти слова, чтобы побудить и мотивировать читателей продвигать сложные темы, они часто имеют противоположный эффект; читатель, который слышит, что что-то «просто», может быть разочарован, когда сталкивается с проблемой. Вместо этого мы поощряем наших читателей, предоставляя им объяснения, необходимые для достижения успеха.

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

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

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

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

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

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

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

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

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

В отличие от сообщений в блогах, мы не используем первое лицо единственного числа (например, «Я думаю…»). Вместо этого мы поощряем использование второго лица (например, «Вы будете настраивать…»), чтобы сосредоточить внимание на читатель и что они сделают. В некоторых случаях мы будем использовать множественное число от первого лица (например, «Мы проверим…»).

Мы поощряем мотивационный язык, ориентированный на результаты. Например, вместо «Вы узнаете, как установить Apache», попробуйте «В этом руководстве вы установите Apache». Такой подход мотивирует читателя и фокусирует внимание на цели, которую ему нужно достичь.

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

Состав

Статьи DigitalOcean имеют последовательную структуру, которая включает в себя введение, заключение и любые предпосылки, необходимые читателю для начала работы. Однако конкретная структура зависит от типа статьи.

Большинство руководств, которые мы публикуем, носят процедурный характер, в котором читатель шаг за шагом проходит через выполнение задачи. Структура процессуальной статьи должна быть:

  • Заголовок (заголовок 1-го уровня)
  • Введение (заголовок 3-го уровня)
  • Предварительные условия (заголовок уровня 2)
  • Шаг 1. Делаем в первую очередь (заголовок уровня 2)
  • Шаг 2 – Дальнейшие действия (заголовок уровня 2)
  • Шаг n — последнее действие (заголовок уровня 2)
  • Заключение (заголовок уровня 2)

У концептуальных статей будет заголовок, введение и заключение, но они могут не иметь раздела предварительных условий или следовать соглашению «Шаг»:

  • Заголовок (заголовок 1-го уровня)
  • Введение (заголовок 3-го уровня)
  • Предварительные требования (необязательно) (заголовок уровня 2)
  • Подтема 1 (заголовок уровня 2)
  • Подтема 2 (заголовок 2-го уровня)
  • Подтема n (заголовок 2-го уровня)
  • Заключение (заголовок уровня 2)

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

  • Заголовок (заголовок 1-го уровня)
  • Вводный абзац
  • Предварительные требования (необязательно) (заголовок уровня 2)
  • Тело статьи
  • Заключительный абзац

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

Заголовок

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

Типичное название процедурного руководства имеет следующий формат: Как <выполнить задачу> с помощью <программного обеспечения> в <дистрибутиве>.

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

Заголовки, которые включают цель (например, «Как разместить веб-сайт с помощью Cloudflare и Nginx в Ubuntu 22.04»), как правило, более информативны для читателя, чем заголовки, в которых нет цели (например, «Как использовать Cloudflare и Nginx в Ubuntu 22.04» ).

Введение

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

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

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

Сосредоточьтесь на читателе и на том, что он сделает. Вместо таких фраз, как «мы научимся», используйте такие фразы, как «вы будете настраивать» или «вы будете строить». Это в значительной степени мотивирует читателя и вызывает у него интерес к вашей теме. Кроме того, сосредоточьте внимание на проблеме, которую решает читатель, а не на технологии. Например, если руководство посвящено созданию проекта с помощью React, вы можете сосредоточить свое введение на проекте, а не на объяснении того, что такое React.

Предпосылки

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

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

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

Общие предварительные условия для системного администрирования и руководств по DevOps включают:

  • Необходимое количество серверов, включая распределение, первоначальную настройку сервера и любые дополнительные необходимые параметры (например, требования к памяти, ключи DO API, IPv6 или частные сети).
  • Установка и настройка программного обеспечения, такого как Apache, стек LAMP или базы данных.
  • Необходимые настройки DNS или SSL-сертификаты.

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

Общие предварительные условия для учебных пособий по разработке программного обеспечения включают:

  • Необходимо локальное программное обеспечение, например Git, Node.js, Python, Ruby или Docker.
  • Дополнительные учетные записи пользователей, такие как GitHub, Facebook, Twitter или другие сервисы, которые потребуются вашему читателю.
  • Учебники, которые помогут читателю начать работу над своим проектом, например Как настроить HTML-проект.
  • Концептуальные статьи, содержащие важную информацию, которая может быть полезна читателю, например, Understanding the DOM.

Например, руководство по созданию и развертыванию приложения Node.js и его развертыванию на сервере Ubuntu с помощью Git может иметь следующие предварительные условия:

Для выполнения этого урока вам понадобятся:

  • Один сервер Ubuntu 22.04, настроенный в соответствии с руководством по первоначальной настройке сервера Ubuntu 22.04, включая пользователя без полномочий root с поддержкой sudo и брандмауэр.
  • Доменное имя, настроенное так, чтобы оно указывало на ваш сервер. Вы можете узнать, как указать домены для дроплетов DigitalOcean, следуя руководству по доменам и DNS.
  • Git установлен на вашем локальном компьютере. Вы можете следовать руководству Contributing to Open Source: Getting Started with Git, чтобы установить и настроить Git на своем компьютере.
  • Локальная среда разработки для Node.js, которую можно настроить с помощью инструкции по установке Node.js и созданию локальной среды разработки для вашей системы.

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

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

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

  • Серверы Ubuntu 20.04, установка программного обеспечения и записи DNS в предварительных требованиях этого руководства по Minio.
  • Обработка нескольких серверов с установкой программного обеспечения в этом руководстве по Nagios и Alerta.
  • Проекты веб-разработки на основе React, прочитав How To Test a React App with Jest and React Testing Library.

Будьте конкретны с вашими предварительными условиями. Обязательное условие, такое как «Знакомство с JavaScript» без ссылки на что-то конкретное, не дает вашему читателю много контекста. Вместо этого перечислите конкретные концепции, которые читатель должен знать, и предоставьте им ресурсы, которые помогут им освоиться, чтобы они могли успешно завершить ваш учебник. Например, используйте что-то вроде \Знакомство с Javascript. Чтобы развить свои навыки, ознакомьтесь с серией статей How To Code in JavaScript».

Шаги

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

Каждый шаг начинается с заголовка уровня 2.

В процедурных учебниках название каждого шага начинается со слова «Шаг» и номера, за которым следует тире. Название шага описывает, что читатели сделают на этом шаге, и использует герундий (-ing слова), например:

Шаг 1 – Создание учетных записей пользователей

После заголовка добавьте вступительное предложение, описывающее, что читатель будет делать на каждом шаге и какую роль он играет в достижении общей цели руководства. Сосредоточьтесь на читателе. Вместо фраз типа «Мы научимся» или «Я объясню» используйте фразы типа «Ты построишь» или «Ты создашь».

Команды в шагах

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

Выполните следующую команду, чтобы отобразить содержимое каталога /home/sammy, включая все скрытые файлы:

  1. ls -al /home/sammy

Переключатель -a показывает все файлы, включая скрытые, а переключатель -l показывает длинный список, включая временные метки и размеры файлов.

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

Запустите программу hello.js:

  1. node hello.js

Вывод программы будет напечатан на экране:

Output
Hello world! This is my first Node.js program!

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

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

Открытие, создание и просмотр файлов

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

Явно скажите пользователю создать или открыть каждый файл, который вы им предложите использовать.

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

Откройте файл /etc/hginx/config с помощью следующей команды:

  1. nano /etc/nginx/sites-available/default

Мы используем редактор nano для руководств по Ubuntu и Debian, так как он уже установлен. Мы используем vi в руководствах по CentOS и FreeBSD. В любом случае избегайте использования touch для создания новых пустых файлов, поскольку ваши читатели могут создавать файлы непосредственно в редакторе.

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

Откройте файл src/App.js в своем редакторе.

Читатель всегда должен знать, с каким файлом он работает.

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

Мы рассматриваем весь код как возможность для обучения. Если вы просите читателя написать код, используйте тот же подход, что и для команд: вводите блок кода с высокоуровневым объяснением того, что он делает. Затем покажите код, а затем озвучьте все важные детали.

Вот пример:

Создайте файл hello.js в текстовом редакторе:

  1. nano hello.js

Добавьте в файл следующий код, который выводит сообщение на экран:

console.log("Hello world!");
console.log("this is my first Node.js program!")

Функция console.log принимает строку и выводит ее на экран в отдельной строке.

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

Это руководство по Docker Swarm — хороший пример того, как использовать наш собственный Markdown, чтобы различать команды, выполняемые на нескольких разных серверах, а также локально.

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

Откройте файл /etc/nginx/sites-available/default в вашем редакторе:

  1. nano /etc/nginx/sites-available/default

Измените значение server_name на ваше доменное имя:

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /usr/share/nginx/html;
    index index.html index.htm;

    server_name your_domain;
...

}

Обязательно объясните, что делает изменение и почему оно необходимо.

Пользовательские рекомендации DigitalOcean по уценке и форматированию разработаны, чтобы сделать инструкции наших руководств максимально удобными для чтения.

Переходы

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

Вот пример перехода в конце шага 1 в этом руководстве о том, как защитить Nginx с помощью Let’s Encrypt в Rocky Linux 8:

Вы установили клиент Let’s Encrypt, но перед получением сертификатов необходимо убедиться, что все необходимые порты открыты. Для этого на следующем шаге вы обновите настройки брандмауэра.

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

Обрамление каждого шага таким образом помогает читателям учиться и мотивирует их продолжать.

Заключение

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

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

Некоторые хорошие примеры включают заключение этого руководства по node-csv.

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

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

Заголовки

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

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

Заголовки шагов также должны использовать герундий, который является словом с окончанием. Пример заголовка шага: Шаг 1 — Установка Nginx.

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

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

Жирный шрифт следует использовать для:

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

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

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

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

Блоки кода

Блоки кода следует использовать для:

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

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

server {
    listen 80 default_server;
    listen [::]:80 default_server ipv6only=on;

    root /usr/share/nginx/html;
    index index.html index.htm;

    server_name your_domain;
...

}

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

Если читатели добавляют строки в уже существующий код, используйте выделение, чтобы указать новые строки или другие изменения. Вот пример из руководства How To Use Go Modules.

Откройте файл main.go из каталога mymodule и добавьте вызов PrintHello, добавив выделенные ниже строки:


package main

import (
	"fmt"

	"mymodule/mypackage"
)

func main() {
	fmt.Println("Hello, Modules!")

	mypackage.PrintHello()
}

В приведенном выше примере все элементы, которые добавит читатель, выделены.

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

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

```command
sudo apt update
```

```super_user
adduser sammy
```

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

Вот как будут отображаться предыдущие примеры:

  1. sudo apt update
  1. adduser sammy
  1. FLUSH PRIVILEGES;

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

Метки блока кода

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

Используйте метки, чтобы пометить блоки кода, содержащие содержимое файла, именем файла. Например, если у вас есть файл с именем app.js, используйте [label app.js], чтобы пометить блок кода:

```js
[label app.js]
console.log("Hello World!");
```

Метка отображается над списком кодов:

console.log("Hello World!");

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

```
[secondary_label Output]
Hello World!
```

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

Output
Hello World!

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

Цвета окружения блока кода

Иногда читатель будет работать на нескольких компьютерах, например, на их локальной машине и на нескольких серверах. Использование разных цветов для отображения среды может облегчить читателям понимание. Markdown от DigitalOcean позволяет окрашивать фон блока кода, добавляя строку с [environment name] в любом месте блока. Варианты для имя: local, второй, третий, четвертый и пятый.

Например, если вы пишете учебник и хотите показать команду, которую следует запускать локально, а не на сервере, вы можете использовать [environment local]:

  1. ssh root@your_server_ip

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

Использование [вторая среда] будет отображаться следующим образом:

  1. echo "Secondary server"

Использование [среда третья] будет отображаться следующим образом:

  1. echo "Third server"

Использование [четвертая среда] будет отображаться следующим образом:

  1. echo "Fourth server"

И [среда пятая] будет отображаться следующим образом:

  1. echo "Fifth server

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

Output
Hello World!

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

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

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

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

Вот отрендеренный результат:

Примечание: это примечание.

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

Информация о DigitalOcean

Выноска [info] полезна при обсуждении конкретных функций DigitalOcean.

Эта функция специфична для дроплетов DigitalOcean.

Переменные

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

Вот пример начальной настройки сервера с Ubuntu 22.04:

В этом примере создается новый пользователь с именем sammy, но вы должны заменить его на имя пользователя, которое вам нравится:

  1. adduser sammy

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

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

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

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

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

При включении изображений в учебник соблюдайте следующие правила:

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

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

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

![Descriptive alt text for screen readers](http://imgur.com/your_image_url “Brief caption here”)

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

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

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

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

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

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

Имя хоста по умолчанию — your_server, хотя вы можете выбрать что-то более описательное в настройках с несколькими серверами, например django\_replica\_1.

Домен по умолчанию — ваш_домен. Для настройки с несколькими серверами вы можете выбрать что-то вроде 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-адреса, используйте адрес в одном из двух блоков, зарезервированных для документации в соответствии с RFC-5737. В частности, мы рекомендуем 203.0.113.0/24 в качестве общедоступных адресов и 198.51.100.0/24 в качестве частных адресов.

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

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

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

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

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

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

При более абстрактном обсуждении многосерверных архитектур используйте термины «основной» и «реплика» или «менеджер» и «рабочий».

Технические рекомендации

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

Перейдите по этой ссылке, чтобы стать автором DigitalOcean.