Технический блог существует ради одного — чтобы читатель перестал мучиться с конкретной проблемой. Поэтому понятность здесь не стиль, а функция: если читатель после вашей статьи не смог сделать то, зачем пришёл, статья не сработала, каким бы точным ни был текст. Хорошая новость в том, что понятность собирается из приёмов, а не из таланта: выбрать уровень читателя, зайти через задачу, дать пример, объяснить термин там, где он впервые встретился, и проверить результат на живом новичке. Разберём эти приёмы по порядку и то, чего в техническом тексте быть не должно.
Сначала читатель, потом текст
Главная причина непонятных статей — автор пишет для себя трёхлетней давности, но не знает об этом. Перед первой строкой нужно ответить на три вопроса. Кто читает: студент, который слышал термин один раз, практик из смежной области или коллега того же уровня? Что он уже умеет — и, главное, чего он точно не знает? Что он должен уметь после прочтения: понять идею, повторить по шагам или самостоятельно починить похожий случай? Ответы стоит записать одной строкой и держать перед глазами: «пишу для верстальщика, который впервые открыл консоль и должен после статьи сам развернуть проект». Такая строка вычёркивает половину лишних абзацев ещё до того, как они написаны.
Второе следствие важнее первого: уровень нельзя менять посередине. Текст, который начинается с объяснения, что такое переменная, и заканчивается тонкостями асинхронного выполнения, не подходит никому — новичок отвалится на середине, а опытный не дочитает начало. Если материал разрастается на два уровня, это два материала, и второй ссылается на первый. Признак, по которому легко поймать сбой: в тексте появляется оборот «как мы помним» применительно к вещи, которую вы ни разу не объясняли.
Объясняйте через задачу, а не через устройство
Учебники идут от устройства: вот компонент, вот его свойства, вот как он работает. В блоге это не работает, потому что читатель пришёл не изучать, а чинить. Заходите с задачи: «страница грузится семь секунд, и виноваты шрифты» — и только потом объясняйте механику ровно в том объёме, который нужен для решения. Теория, поданная после боли, запоминается; теория до боли пролистывается. Тот же приём спасает и от бесконечных предисловий: если первые два абзаца можно заменить на одно предложение с описанием симптома, так и сделайте. Читатель технического блога открывает статью с раздражением от незакрытой задачи — не заставляйте его ждать.
Код и скриншоты: сколько и какие
Пример кода должен запускаться целиком. Обрывок с многоточием вместо половины строк экономит вам место и стоит читателю получаса на угадывание. Если фрагмент длинный, вынесите полную версию отдельной ссылкой на репозиторий, а в тексте оставьте кусок с комментариями на русском. Скриншот нужен там, где словами описывать путь дольше, чем показать: настройки в панели, результат в браузере, сообщение об ошибке. Но скриншот не заменяет текст — по картинке нельзя искать, её не читает голосовой помощник и она мгновенно устаревает при обновлении интерфейса. Поэтому под каждым изображением коротко пишите словами, что на нём и что нужно нажать.
- Код — минимальный рабочий пример, а не кусок боевого проекта с вашими настройками.
- Версии обязательно: то, что верно для одной версии библиотеки, через год ломается.
- Скриншот обрезайте до нужной области и подписывайте словами, что на нём происходит.
- Сообщение об ошибке давайте текстом, а не картинкой, — его будут искать копированием.
Термины: сноска вместо словаря
Два одинаково плохих решения — вываливать в начале словарь из двадцати определений и не объяснять ничего. Рабочий вариант посередине: термин объясняется ровно там, где встретился впервые, в одной фразе и без ухода в сторону. Лучше всего работает формат сноски или вставки в скобках: слово, тире, десять слов человеческого смысла. «Кеш — промежуточное хранилище, где лежит уже посчитанный ответ, чтобы не считать его заново». Такой сноски достаточно, чтобы новичок не выпал из текста, и она не раздражает того, кто термин знает. Если объяснение не помещается в одну фразу, значит, это тема для отдельной статьи, а здесь нужна ссылка на неё.
Проверка на новичке
Единственный надёжный способ понять, понятно ли написано, — дать текст человеку, который задачу не решал. Автор не может проверить себя сам: он видит в тексте то, что знает, а не то, что написано. Найдите коллегу на уровень ниже, знакомого из смежной области или участника профильного чата и попросите не оценивать, а выполнить инструкцию вслух. Все места, где он остановился, переспросил или полез гуглить, — дыры в тексте, даже если формально там всё верно. Чинятся они добавлением одной фразы, а не переписыванием раздела.
- Дайте статью человеку, который задачу раньше не решал.
- Попросите выполнять шаги вслух и не подсказывайте, как бы ни хотелось.
- Записывайте каждую паузу и каждый вопрос — это и есть список правок.
- Закройте дыры одной-двумя фразами на месте, где человек споткнулся.
- Через неделю перечитайте сами: свежий взгляд ловит то, что тестировщик пропустил из вежливости.
Чего в техническом тексте быть не должно
Первое — жаргон без расшифровки. Профессиональный сленг экономит слова среди своих и полностью закрывает текст для остальных; если слово попало в статью, оно должно быть объяснено или заменено. Второе — снисходительность. Обороты «элементарно», «всем известно», «тут всё очевидно» не ускоряют чтение, зато сообщают читателю, что он глупый, и заодно позволяют автору не объяснять сложное место. Третье — пересказ документации своими словами: он устаревает быстрее оригинала. Четвёртое — умолчание о том, что у вас не получилось: честный абзац про грабли ценнее трёх абзацев про успех, потому что читатель наступит ровно на них.
Понятно написано не тогда, когда прочитал и кивнул, а тогда, когда закрыл вкладку и сделал.
Соберите всё вместе — уровень читателя в одну строку, заход через задачу, рабочий пример, сноски к терминам, проверка на новичке — и технический блог начнёт приводить не случайных посетителей, а людей, которые возвращаются с каждой новой задачей. Из мелочей заметнее всего качество иллюстраций: аккуратные схемы и снимки железа отличают живой блог от перепечатки, и снимать их стоит уметь самому — этому учат на курсах Фотофакультета имени Ю. А. Гальперина. А если писать получается, но на продвижение и поиск читателей времени не остаётся, эту часть берёт на себя агентство «Креатифф».
Вопрос — ответ
Как понять, для кого писать технический текст?
Перед первой строкой ответьте: кто читает, что он уже умеет и чего не знает, и что он должен уметь после прочтения. Запишите ответы одной строкой и держите её перед глазами.
Как объяснять сложное в техническом блоге?
Заходите с задачи, а не с устройства: сначала опишите симптом, например страница грузится семь секунд, и только потом объясняйте механику в том объёме, который нужен для решения.
Как объяснять термины в техническом тексте?
Объясняйте термин там, где он встретился впервые, в одной фразе, например по формату сноски: «кеш — промежуточное хранилище, где лежит уже посчитанный ответ». Если объяснение не помещается в одну фразу, дайте ссылку на отдельную статью.
Как проверить, понятна ли техническая статья?
Дайте текст человеку, который задачу раньше не решал, и попросите выполнять шаги вслух, не подсказывая. Каждую паузу и каждый вопрос записывайте: это и есть список правок, а дыры закрываются одной-двумя фразами.
Какие примеры кода и скриншоты нужны в технической статье?
Пример кода должен запускаться целиком, а версии библиотек стоит указывать обязательно. Скриншот нужен там, где словами описывать путь дольше, и под каждым изображением коротко пишите, что на нём и что нужно нажать.
