Муки вступления

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

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

Читатель находится перед выбором: есть миллион других статей, которые стоит прочитать. Почему именно твоя? Если читатель не вкусит обещанной выгоды за первые 20 минут, он просто закроет страницу. Дай ему причину продолжить.

Когда разработчик начинает читать пост, в его голове возникают два вопроса:

  1. Эта статья написана для кого-то вроде меня?
  2. Что я из неё получу?

Ответь на оба вопроса за счёт названия и первых трёх предложений.

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

Вот пример статьи, которая сразу переходит к делу:

✓Хорошо Начни с того, какую пользу получит читатель

if got, want: A Simple Way to Write Better Go Tests

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

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

Предисловие тоже считается мучительным вступлением

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

✗Плохо Заставляй читателя пробираться сквозь лишнее предисловие

«Читатель знает всё, что знаю я, кроме одного»

Хорошие преподаватели сравнивают новые концепции с тем, что знакомо читателю. Например, объясняя Jellyfin, можно сказать: «Jellyfin — это потоковый сервис вроде Netflix, но с открытым исходным кодом и приватный, поэтому никто не следит за твоей историей просмотров». Сложная часть — понять, что знакомо именно твоему читателю.

✗Плохо Предполагай, что читатель знает всё, что знаешь ты

В этой статье я представлю Docker разработчикам, которые о нём никогда не слышали.

Docker простой. Это просто красивый интерфейс к Linux cgroups. Знаешь jails в *BSD? Docker — это Linux версия того же.

Много разработчиков хотят использовать Docker, но не знают про cgroups, jails или *BSD. Они могут даже не знать, что такое Linux, особенно если ищут введение в Docker.

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

✓Хорошо Минимизируй допуски о знаниях читателя

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

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

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

– Tyler Cipriani, когда я задал вопросы о целевой аудитории при редактировании "The future of large files in Git is Git"

Чрезмерная полнота ссылок

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

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

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

✗Плохо Полагайся на ссылки, чтобы объяснить термины

Установи правила фильтра, чтобы запретить трафик к базе данных.

Справочник FreeBSD выше — отличный ресурс, но глава про фильтры занимает 20 000 слов. Когда ты ссылаешься на столько текста, ты дашь читателю огромный объём работы.

Вместо полагания на ссылки дай читателю минимальное объяснение, необходимое, чтобы понять твою статью.

✓Хорошо Резюмируй информацию за ссылкой

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

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

Ошибка инъекции сиквела

В наши дни всё либо сиквел, либо перезагрузка — включая блог-посты. Встречаю множество постов, которые начинаются так:

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

Горькая правда: большинство читателей не прочитали часть первую. Если ты предполагаешь, что предыдущая статья свежа в памяти, читатель подумает: «Получается, мне нужно сначала прочитать другую статью?»

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

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

Чрезмерная формальность

Начинающие авторы почему-то уверены, что писать нужно напыщенно и формально, чтобы их воспринимали всерьёз:

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

Ты же не пишешь для восьмидесятилетних управленцев IBM образца 1988 года. Разработка ПО — одна из самых неформальных белых воротничков. Человек, читающий твою статью, вероятно, сидит в пижаме и тапках, ест хлопья прямо над клавиатурой. Он не ожидает и не хочет, чтобы ты говорил как юридический документ.

Пиши так, как ты говоришь.

✓Хорошо Пиши как ты говоришь

Мы попробовали несколько статических анализаторов на этом проекте.

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

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

– Joel Spolsky, "The Perils of JavaSchools"

Не его лучшее предложение, но оно ловит стиль. Он пишет развязно, тепло, без претензии. Звучит как рассказ за обедом между коллегами. Такой же стиль у Kathy Sierra, Terence Eden и Raymond Chen. Они не пытаются звучать умно — они просто звучат как сами себя, и это нравится читателям.

Небрежность в вёрстке HTML

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

Переполнение на мобильных

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

Firefox и Chrome имеют встроенный режим мобильного просмотра. Посмотри статью в режиме мобильного до публикации и проверь типичные ошибки вёрстки.

Не пренебрегай мобильными читателями. По аналитике, 25% читают эту страницу на телефонах. На моём личном блоге это 35%.

Нечитаемый шрифт

Выбери цвет и гарнитуру, которые легко читать. Хватит писать тёмно-серый на светло-сером фоне. Firefox и Chrome имеют встроенные инструменты, которые находят низкоконтрастный текст.

Инструмент доступности Firefox находит низкоконтрастный текст

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

Итоги

  • Дай читателю причину продолжить. Ответь на оба вопроса в названии и первых трёх предложениях.
    • Обычные причины: интересный рассказ, полезная техника, понятное объяснение концепции.
  • Проверь допуски о том, что знает читатель.
    • Думай о том, какие концепции ты считаешь знакомыми, и перечитай статью, проверив совпадения.
  • Читатель должен понимать статью от начала до конца без кликов и подсказок.
    • Ссылки помогают копать глубже, но должны быть бонусом, а не требованием.
  • Избегай представления статьи как продолжения другой.
    • Предполагай, что большинство не читали твои прошлые посты. Резюмируй нужное вместо ожидания, что они прочитают всё.
  • Забудь про формальность. Пиши как ты разговариваешь.
  • Проверь статью в мобильном режиме браузера.
    • Убедись, что текст не выходит за границы экрана и не требует горизонтального скролла.
  • Используй инструменты браузера, чтобы найти низкоконтрастный текст, который сложно читать.

Иллюстрации «Not Quite How Developers Read» и «What the Reader Knows» создал Piotr Letachowicz.