О, статьи — их тысячи! Их пишут сейчас в огромных масштабах все, кто только пожелает. Но как начать их писать, если вы программист? Каким должно быть введение и как не погубить текст? И это только малая толика того, на что эта статья не ответит! Шучу-шучу… Конечно, мы затронем эти темы, но, как всегда, думайте своей головой, ибо истины не существует.

Дисклеймер: Всё написанное — имхо автора. И, да, он был однажды программистом…

Код как искусство

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

Вы бы знали, как часто мы встречаем ошибки, вызванные опечатками в проектах! Вот, например, статья, написанная исключительно про опечатки в Chromium. Статьи про проверку проектов — это пехота нашей маркетинговой стратегии. Ошибок всегда в достатке, формат не сложен, да и читателям нравится. Впрочем, не будем углубляться в эту тему. К тому же, скоро (по крайней мере однажды…) выйдет статья о том, как мы вообще пишем их и что это за формат такой. Если интересно, то подписывайтесь на наш хабр, чтобы не пропустить её 🙂

Итак, а что там всё-таки с кодом? Как я уже говорил — это подробное описание, что и как делать для несносной аудитории процессоров. Так что в той или иной степени каждый программист умеет чётко излагать свои мысли. Всё, конечно, не так гладко. Нельзя напрямую сравнивать язык программирования и обычные "человеческие" языки. Или всё-таки можно?

Вот одно из исследований активности мозга во время чтения кода. Да здравствует фМРТ! В ходе этого исследования было обнаружено, что во время чтения кода у программистов задействуются 6, 21, 40, 44 и 47 поле Бродмана. Честно говоря, я понятия не имел, что это означало, пока не добрался до статьи на вики. Если перевести результат исследования на обычный язык, то получится примерно следующее:

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

N.B. Если у вас есть лучшие варианты перевода, то обязательно пишите – поправим вместе 🙂

Я ничего не понимаю, где комментарии?

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

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

— Да ладно тебе, Дим, тут же везде есть комменты…

— Как же ты достал! Чеши разбивай это на отдельные методы и не вздумай больше писать всё в кучу!

Что я вообще этим хотел сказать? Хороший код легко понять и без сопроводительных книг с документацией. Ведь помимо компиляторов (или интерпретаторов) его приходится читать и править другим разработчикам. Так что задача сильно усложняется тем, что на высокоуровневом языке приходится сесть сразу на два стула…

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

• чётко и ёмко формулировать свои мысли (не обязательно с первой попытки);
• быть последовательным в повествовании (во время споров, какой язык программирования лучше);
• анализировать написанное и находить различные проблемы (но только не в своём коде);
• абстрактно мыслить (за стаканчиком кофе где-нибудь в курилке);
• очень долго сидеть и читать всякий текст (особенно в день X).

Куда держим курс?

Итак, что нам понадобится для начала:

• разработчик, умеющий писать хороший код — 1 шт.;
• тема для статьи — 1 шт.;
• свободное время — NaN

Segmentation fault

А что там с темой для статьи? Честно говоря, я и сам не умею придумывать темы для статей или выступлений. Обычно мне что-нибудь приходит в голову, и я по привычке записываю это на первый попавшийся клочок бумаги. Спустя n-е количество времени он попадается мне на глаза и наступает процесс получения бону написания статьи.

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

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

Не пытайтесь искать это в названиях разделов… xD

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

И да, введения здесь нет. О нём будет много позже, так что не волнуйтесь о нём до самого конца 🙂

И что нам делать со всем этим?

Скелет из топиков готов, а значит, пришло время открыть Word, Vim, Emacs etc. Одним словом, то, где вам комфортно писать текст. Лично я пишу все статьи изначально в ворде, а потом при помощи внутренней утилы конвертирую в формат для Habr’а. Ну, ладно, опустим это…

Самое трудное — это начать… Действительно, первые два-три предложения задают темп тексту. Своего рода мелодия, которая должна плавно провести читателя сквозь темы. Но не стоит отчаиваться, если не понятно, о чём писать.

Что делаю я в самом начале? Наливаю стаканчик кофе, затем надеваю наушники и включаю какой-нибудь ambient, (музыка без слов на фон) после этого представляю монолог с читателем, посматривая на свой скелет. В случае этой статьи топик был "Код и обычный текст" (не ищите его — он был переименован).

Так эта статья и началась. А затем я вспомнил про то, что у нас есть статья исключительно про опечатки и плавно привёл к ней. Разумеется, эта статья существует не просто для того, чтобы порадовать читателей контентом. Будем реалистами — в той или иной степени это маркетинг. Однако мы придерживаемся идеи взаимной выгоды:

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

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

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

Ну, ладно, давайте отвлечёмся от этого и вспомним, что там было дальше по тексту. Я писал о том, что есть много похожего между чтением текста и кода. Но, конечно, тыкнуть пальцем в небо было бы как-то глупо. Поэтому я решил погуглить это – вдруг, что полезное найдётся…

В итоге я наткнулся на небольшую заметку "Разработка и мышление: как работает мозг во время кодинга", где и нашёл ссылку на исследование, которое указал в начале статьи. Вот примерно так и был написан первый кусочек текста. Надеюсь, что этот пример может вам пригодиться 🙂

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

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

Волшебство рефакторинга

На этом этапе вы уже — счастливый обладатель практически готового текста! Дело осталось за малым: обновить названия, заняться редактурой и завершить ещё пару дел до финальной точки.

Итак, названия. Лучший вариант — прочитать каждый "раздел" текста и дать ему подходящее имя. И, нет, оставлять первоначальные названия — не всегда лучшая идея. Как бы мы ни пытались писать по теме, в любом случае куда-то наша мысль да уходит. Конечно, я не отрицаю вероятность того, что это всего лишь мой личный взгляд на это и в действительности всё совершенно иначе…

Note. Попробуйте в названиях вопросы. Они создают некоторую интригу и повышают вероятность пробудить интерес у читателя.

Покончив с названиями, можно отправиться за кофе. Крепкий и ароматный… Пусть он поможет сконцентрировать мысли и направить их в нужное русло! Мне, правда, прока уже нет от него 🙁

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

Как понять, что с редактированием пора заканчивать? Ну, вот небольшой чек-бокс:

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

Последний пункт, само собой, самый важный — главное, чтобы вам нравилось, и вы точно однажды найдёте свою аудиторию. Ну, а что я имел в виду про разрежённость текста? Важно соблюдать баланс между концентрацией сложных фактов, вроде точных данных, дат, имён etc., и пустым текстом (той самой всем известной водой).

Где-то на этом моменте у вас мог возникнуть праведный гнев: "Да каждая вторая статья — сплошная вода! Куда больше-то?!". И вы будете абсолютно правы, но взгляните на это с другой стороны. Где воды нет совсем? В справочниках. Действительно ли их увлекательно читать?

Here We Go Again…

О, дивное время введения! Ненавижу его… Нет ничего труднее этого, ведь именно оно должно заинтересовать читателя. Вы можете написать совершенную статью, но при этом без вкусного введения до читателя она не доберётся.

"Какое ещё введение?" — подумали вы, читая предыдущий абзац. Да, я из тех странных людей, которые пишут введение в последнюю очередь. И дело тут не только в моей лени (впрочем, и без неё не обошлось)… Обычно трудно понять какой выйдет статья в самом начале. Можно, конечно, составить чёткий план и строго ему следовать, но в реальности получается всегда нечто отличное от начального курса. Факторов уйма: от лени, до настроения. Так что лучше всего оставить введение на самый конец, чтобы знать в точности, что будет в самой статье.

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

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

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

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

Note. Придерживайтесь средней длины введения (6-8 предложений), так как излишне большие введения могут отпугнуть читателя.

Последнее, что осталось сделать — дать статье название. Всё, что справедливо для введения, справедливо и для заголовка. Так что вложите в него все силы, которые у вас остались. Это финишная прямая. Кстати, обычно заголовки, содержащие вопрос, более привлекательны для читателя.

В долгий путь

Вот ещё одна статья для нашего блога готова. Что с ней будет дальше? Она отправится на вычитку. Я всегда боюсь этого момента, ведь тот, кто читает её, может совершенно не понять моего юмора или отсылок. И что после этого ты скажешь? Нет, это понятный юмор, просто ты его не понял? Иногда за такие фрагменты приходится действительно бороться, приводя аргументы и отстаивая их, как в суде.

С другой же стороны, временами действительно находятся проблемные места в тексте. Так что нельзя назвать это очевидным злом. Нет, это, скорее, неизбежная необходимость. Впрочем, одними руками всё не закончится — потом статья отправится на редактуру, после которой — на перевод (за редким, как эта статья, исключением).

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

---

На правах рекламы

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