Отправив в редакцию приблизительно 45ю статью, которую пришлось редактировать в этом году, натолкнулся на мысль, что очень приходится указывать новым и старым авторам на одни и те ошибки. Поэтому все рекомендации решил собрать все в виде советов: “Как написать правильную статью для самага”.
текущая версия 0.01 от 20.09.2012

Не бойтесь писать, многие боятся начать, боясь, что не получится. В редакции не звери и подходят к каждой статье взвешенно. Вначале оценивается полезность статьи, а потом стиль и прочее. Если статья полезна, то будут выданы рекомендации. То есть задача правильно изложить основную мысль статьи. Да, иногда приходится редактировать по 10+ раз. Зато, в конце концов, сами авторы открывают в описываемой проблеме, то чего они раньше не замечали и смотрят на продукт по-другому. Но аналогично не проходит и шара . Да и не спорьте с редактором, считая его “не в теме”. Редактор смотрит на статью глазами среднестатистического читателя. Его задача сделать статью максимально понятной всем, в которой не будет неточностей, недомолвок и несказанно ничего лишнего. А поверьте, они есть даже у постоянных авторов.
Комментарии редактора не нужно воспринимать как обиду и попытку как-то унизить автора. Редактору этого просто не нужно, в этом нет смысла. В некоторых статьях комментарии занимают до 25% объема. Согласитесь это много. И начинаешь сокращать, просто подсказывая, на какие моменты следует обратить внимание. Большинству авторов этого достаточно. Комментарии следует воспринимать как пожелание, за статью ответственность несет автор и пишет его сам, ориентируясь на рекомендации редактора. Хотя если редактор будет не согласен с окончательным текстом, он скажет об этом прямо, и решение по дальнейшей публикации будет принимать кто-то другой.

1. Для начала следует ознакомиться с общими рекомендациями http://samag.ru/main/part/5

Среди прочих прошу особо внимание обратить на следующие:

• статья должна быть оригинальна и не нести рекламный характер одного продукта
• выбор описываемой технологии или продукта должно быть обосновано, указаны плюсы и минусы – то есть не нужно писать, что “будем ставить MS Windows и точка”. Не пройдет. В начале придется пояснить, зачем он нужен, какое преимущество имеет перед другими ОС, сколько нужно будет потратить на внедрение. Очень хорошо смотрятся в статьи, в которых автор показывает, как он выбирал решение среди прочих, обосновывая почему он остановился именно на этом и зачем вообще нужен этот класс продуктов и какие тенденции в развитии этого сектора.
  Все это расписано опять же в рекомендациях:
• начало статьи должно содержать два-три��вводных абзаца, где необходимо описать:
• Проблему в бизнесе, которую нужно решить, или процесс, который надо улучшить.
• Какие из уже имеющихся вариантов решения – программные продукты, аппаратные средства и т.п. – известны автору.
• Кратко перечислить причины, почему эти варианты не подходят.
• ответить на вопрос: «Могу ли это я использовать в своей работе?»
• объем не должен превышать 20 000 зн – от себя добавлю, что нужно следить за двойными пробелами (это мешает верстке), а отступы делать табуляцией.
• тема должна быть раскрыта – прочитав, читатель должен понять, о чем статья и не почувствовать что ему чего-то недосказали. Если планируется продолжение об этом обязательно нужно сказать в выводе сориентировав читателя в том о чем там пойдет речь далее.
• Статьи следует присылать в текстовом виде, предпочтительно в формате RTF или DOC – некоторые редакторы используют LibreOffice, некоторые MS Word, иногда приходится работать удалено с чужого ПК. При конвертировании возникают проблемы, например последний случай — потерянные пробелы, которые хорошо заметны в тексте, но тяжело отследить в листингах. С RTF и DOC пока такого не наблюдалось.

2. Кроме этого должен быть врез до 160 зн. описывающий кратко, о чем ЭТА статья. То есть не нужно говорить во врезе, что мол когда то автор написал статью и теперь решил её продолжить. Это плохой пример. Нужно сказать, о чем именно пойдет разговор сейчас. Но в первых абзацах нужно дать информацию о предыдущих частях. Особенно в тех случаях если автор будет ссылаться на них далее.
К врезу и первым 2-3 абзацам нужно подходить чуть ли не более тщательно, чем к написанию всей статьи. Многие читатели, принимают решение о дальнейшем прочтении статьи именно после первых абзацев. Здесь главное зацепить читателя, рассказав, о чем статья и почему именно эта статья – проблема, продукт и пр. нужно применить.

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

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

5. Нужно называть вещи своими именами. То если компания себя на сайте называет NVIDIA, то в тексте не должно быть nVidia, Nvidia и т.п. Причем одинаково она должна называться по ВСЕМУ тексту. Если вещь официально называется гипервизором, то ее так и нужно называть. Если автору не нравится официальный термин, то можно об этом сказать и в дальнейшем пользоваться все равно официальной терминологией. Ведь на других ресурсах, в интерфейсе и документации будут использованы именно принятые в продукте термины. Не нужно путать читателя. Также не может быть программа одновременно быть еще и утилитой и пакетом. И т.п.

6. Использовать русскоязычные устоявшиеся термины. То есть не нужно писать в тексте firewall, когда есть: межсетевой экран, брандмауэр, фаервол наконец. Также не нужно смешивать английские и русские слова. Например, часто пишут web-сервер, а ведь есть устоявшийся термин веб-сервер. И использовать сленг. Лог >>> журнал.

7. Очень плохо смотрится постоянное обращение к читателю: мы настроили, вы можете, у вас под руками, мы получили … Такие фразы захламляют текст, ослабляя внимание, не неся при этом никакой полезной информации. В некоторых изданиях это кстати прямо запрещено и к читателю имеет право обращаться только ГлавРед на своей странице. Ни что не мешает вести разговор от третьего��лица.

8. Правильная структура. Собирайте все сходные факты/информацию в одном месте/блоке. Так легче воспринимается ТТХ, где ни будь вначале статьи или во врезке, чем она же, но размазанная по 6 страницам текста. Статья должна содержать заголовки и подзаголовки. Хорошее правило 1 печатная страница 1-2 подзаголовка. Найти быстро информацию в большом неструктуризированом тексте невозможно.
Информация должна быть к месту, т.е. не нужно в процессе установки Linux, вдруг вспоминать популяции пингвинов. Если устанавливается что-то сложное, лучше в первой части раскрыть все термины, факты, структуру и объяснить, чтобы в процессе просто упоминать их, не объясняя. Все факты и информация, термины должны быть обязательно озвучены и понятны читателю. По тексту не должно всплывать известных только автору названий сервисов, файлов и прочего, если только они не являются общеизвестными или их знание подразумевает уровень статьи. То есть говоря об подключении сервиса к Active Directory,озвучивать что такое Active Directory на трех абзацах вовсе не обязательно.

9. Снимки – рекомендовано PNG, без LZW-компресии. Здесь ничего не обычного. Только пытайтесь оценить, как будут выглядеть снимки при меньшем разрешении и на бумаге. Черный терминал с белым текстом практически не читаем. То есть вместо RGB нужно думать о CMYK. И главное. Снимок должен ДОПОЛНЯТЬ текст, а не его заменять. Дизайнер может вставить рисунок куда угодно (точнее удобно), а мы вынуждаем читателя бросить текст и искать рисунок, чтобы понять о чем речь.
Неправильно:

“отобразится следующее окно посмотрите на рис 1”.

Правильно

Отобразится окно настройки веб-сервиса (рис.1) на котором …..

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

11. Краткость – сестра таланта. Отлично читается статья, когда в ней нет ничего лишнего, все строго по теме. А поэтому в основном тексте не должно быть никаких отклонений. Все отступления, интересные факты убираем совсем, пишем отлельную статью или выносим во врезку. Это только улучшает восприятие материала. Читатель сам найдет время их посмотреть, когда посчитает нужным. Не нужно захламлять статью всеми известной автору информацией по вопросу. Да, знание это хорошо, но пока их читаешь, начинаешь забывать, о чем вообще статья. Пишите строго по теме.
Если автор допускает, что читатель владеет некоторыми минимумом по теме, то нужно этого придерживаться по всей статье. Например, описывая продукт, базирующийся на Linux, и сказав что “установка дистрибутива стандартна и вообще это CentOS”, далее не нужно расписывать принципы работы SSH и прочее. Часто встречается ситуация, когда автор использует несколько коротких предложений сходных по смыслу и даже на 25% по содержанию и которые можно объединить в одно без изменения смысла. Или сложные фразы, которые можно сократить. Да платят за объем, но пожалейте читателя, которого все это утомляет и запутывает восприятие.
Русский язык в отличие от английского допускает опускать слова по контексту. Мы же не говорим “Открыть эту дверь”, стоя перед единственной дверью. Достаточно просто, сказать: Открыть дверь.
Например: осуществить привязку – привязать и пр.

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

Чтобы настроить, то-то нажимаем это. Дальше, чтобы настроить это, нажимаем то-то.

Можно ведь сказать, по-другому.

Сервис обеспечивает супер-пупер шифрование …. настройки которого производятся в …. Еще одна полезная функция … настраивается в ….. .

Или

В панели управления выберите Action (Действие) > IIS and SAM Web Services (Веб-службы IIS и SAM) > OTP Web Service (Веб-служба OTP).

Должно быть написано, как-то так.

OTP сервис работает как …. которая … для ее настройки вызываем

Такой подход поможет в том числе и избежать повторов.

13. Комментарии и правки в статье подсвечиваются другим цветом. Желательно все исправления и свои комментарии также помечать, чтобы было удобно сориентироваться. И просьба после всех правок перечитать повторно весь текст. Номер версии файла после правок увеличиваем на 1, чтобы не было путаницы.