В рамках коммьюнити Vscale мы планируем создать большую коллекцию материалов, посвященных серверному администрированию и программированию. К созданию этих материалов мы приглашаем всех пользователей нашего сервиса.
Чтобы все тексты, публикуемые на коммьюнити-портале, были качественными, интересными и полезными, мы составили подробное руководство для авторов статей.
Стиль
Все статьи, публикуемые на портале, должны отвечать следующим требованиям:
-
Простая и понятная манера изложения. Хорошая статья должна быть понятна любому читателю — в том числе совсем неопытному. Поэтому старайтесь писать как можно проще и не употребляйте сложной терминологии там, где без неё можно обойтись.
-
Грамотность. Перед публикацией статьи обязательно проверьте её на наличие орфографических и пунктуационных ошибок (это можно сделать при помощи специализированных онлайн-сервисов). При наличии большого количества ошибок мы оставляем за собой право отказать в публикации статьи.
-
Полнота. Статья должна описывать все технические процедуры максимально подробно. Каждая приводимая в тексте команда должна сопровождаться детальным комментарием. Прежде чем предложить пользователю выполнить какую-либо команду или отредактировать конфигурационный файл, поясните, зачем нужно это сделать.
-
Практический характер. В статье должно быть описано, как решать конкретную практическую задачу на базе инфраструктуры Vscale. Старайтесь описать всё так, чтобы по прочтении статьи пользователь смог самостоятельно выполнить все необходимые действия по установке/настройке ПО и чтобы у него не возникало никаких вопросов.
При необходимости приводите в статье ссылки на другие материалы (лучше всего — на материалы, уже опубликованные на нашем портале). Главное, чтобы пользователь имел в своём распоряжении полное и самодостаточное руководство, и ему не приходилось бы самостоятельно искать дополнительную информацию. -
Дружественный, но не фамильярный тон. Будьте максимально дружественны по отношению к пользователю, но не перегибайте палку: никаких обращений на “ты”, шуток и жаргонизмов.
Структура
Статья обязательно должна включать следующие элементы
-
Заглавие;
-
Введение;
-
Технические требования;
-
Шаг 1…
-
Шаг 2…
-
….
-
….
-
Шаг N — последний;
-
Заключение.
Ниже мы опишем требования к каждому из этих элементов более подробно.
Заглавие и введение
Статья должна иметь заглавие вида “Как установить (настроить) X на сервере с установленным дистрибутивом Y” или “Установка (настройка) X на сервере с дистрибутивом Y”. Мы оставляем за собой право изменить заглавие , если оно не соответствует описанным требованиям.
Каждая статья начинается с введения, в котором разъясняются следующие моменты:
-
какова цель статьи, чему научится пользователь по прочтении;
-
особенности описываемого программного продукта (постарайтесь дать краткую, но в то же время ёмкую справку);
-
практические преимущества описываемого программного решения (дайте аргументированное объяснение, почему читатель должен использовать именно его).
Сложные руководства могут состоять из нескольких частей. В этом случае во введении стоит кратко описать структуру цикла статей.
Технические требования
Раздел “Технические требования” включает следующую информацию:
-
для какого именно дистрибутива Linux предназначены ваши инструкции;
-
каковы оптимальные технические характеристики сервера, на котором будет установлено описываемое вами ПО;
-
ссылки на руководства по установке и настройке необходимых зависимостей (веб-серверов, баз данных и т.п.).
Это раздел должен служить чек-листом для читателя, поэтому будьте внимательны при его составлении, особенно если речь идёт о сложных и требовательных к системным ресурсам программным решениям.
Помните о главном: всё, что вы описываете в статье, должно быть реализуемо и воспроизводимо на базе Vscale. Если ваша статья, например, написана на базе дистрибутива Linux, образов которого в Vscale нет — мы не примем её к публикации.
Пошаговые инструкции
Все описания процедур установки и настройки должны быть пошаговыми; каждый шаг описывается в отдельном разделе.
Рекомендуемая структура раздела выглядит так:
-
заглавие;
-
вводная фраза (разъясняет, чему именно посвящен раздел);
-
одна или несколько команд, при помощи которых выполняются описанные в разделе действия;
-
подробный комментарий к команде (пояснения по синтаксису, ожидаемый результат выполнения).
Не забывайте, что большую часть читателей нашего портала составляют именно начинающие пользователи, и старайтесь делать комментарии к командам как можно более полными и в то же время понятными. То же самое касается скриптов, фрагментов конфигурационных файлов и примеров кода.
Для дополнительной наглядности в статьях можно и нужно использовать иллюстрации: скриншоты, схемы и т.п.
Не публикуйте фрагменты программного кода, конфигурационных файлов и скриптов в виде изображений.
Описывайте действия, которые читателю нужно выполнить, так: “мы настроим…”, “мы установим…”, “выполним команду…”), отредактируем конфигурационный файл” и т.п., или так: “выполните команду”, “отредактируйте конфигурационный файл” и т.п.
По возможности старайтесь не употреблять глаголы в форме страдательного залога (за исключением редких случаев, когда это действительно оправдано).. Лучше написать “Мы установили программу X”, чем “Программа X программа была установлена нами”.
Если вы употребляете в статье специальные термины, обязательно давайте все необходимые определения и пояснения. Не допускается использование профессиональных жаргонизмов — мы всё-таки пишем для широкого круга читателей.
Для каждого иноязычного термина старайтесь найти эквивалент и дать перевод, хотя бы примерный. Не употребляйте английские слова и выражения в русском тексте: ералаш из русских и латинских букв (“установка Riemann’а”, “работа с Jenkins’ом” и т.п.) делает статью менее читабельной и затрудняет понимание.
Примеры команд
Все примеры команд, фрагменты программного кода и конфигурационных файлов заключайте в тэги <pre>...</pre>, например:
<pre>
$ sudo apt-get install nginx
</pre>
Модерация статей
К рассмотрению принимаются только готовые статьи, оформленные в соответствие с требованиями, приведенными выше. Черновики статей мы не принимаем.
Обратите внимание! Если публикация отклоняется, мы более не храним у себя её текст, поэтому заранее дублируйте важные сведения у себя.
- Срок модерации статьи составляет от 1 до 3 дней.
- Модерация подразумевает проверку представленной инструкции на полноту и выполнимость, а также проверку текста на предмет орфографических, стилистических и пунктуационных ошибок.
- Если текст в целом соответствует требованиям, описанным в нашем Руководстве по стилю, и содержит лишь минимальные недочёты (опечатки, незначительные пунктуационные ошибки, незначительные ошибки в синтаксисе команд), модератор самостоятельно вносит необходимые исправления и публикует текст.
- При необходимости модератор может отправить текст на доработку. Пользователю при этом нужно отправить сообщение с указанием всех ошибок и рекомендациями по их исправлению.
- Не допускается публикация фрагментов кода и конфигурационных файлов в виде изображений (скриншотов консоли).
- Модератор имеет право отказать пользователю в публикации текста, если:
- текст не имеет никакого отношения к Vscale и не представляет никакой практической ценности для пользователей сервиса — например, написан на материале дистрибутива Linux, которого в Vscale нет;
- текст содержит большое количество орфографических и пунктуационных ошибок;
- текст уже был опубликован ранее на других сайтах;
- если пользователь не внёс указанных модератором правок в течение недели с момента отправки текста на доработку.
6. В случае отклонения статьи модератор отправляет автору уведомление об отказе. Также модератор оставляет за собой право отклонять статьи без объяснения причин.