Pull to refresh

Авторам технических текстов: как писать о сложном и не быть занудой?

Reading time5 min
Views5.3K
Потребление контента похоже на процесс приёма пищи. Обычно мы тратим деньги на калории, но важна не только калорийность. Чем еда полезнее, вкуснее и красивее, тем больше мы её хотим. Всегда можно прийти в магазин, купить продуктов и приготовить всё самому. Но для этого нужно уметь готовить. Так и с контентом.

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

Найдите читателя
Чем лучше мы представляем портрет нашего читателя, тем лучше можем написать статью. Важно понять, какой жизнью живёт читатель, чем интересуется. Он работает в сфере IT? Профессионал или любитель? Зашёл на сайт решить задачу или расслабиться?
Здесь мы определяем, насколько «богат» наш посетитель. Сколько он готов потратить своих умственных сил на наш контент? Он согласен основательно сесть за искусно приготовленный лонгрид или хочет быстро перехватить сладкого и вернуться к своим делам?
Ответ на вопрос «кто мой читатель» даёт понять, насколько глубокую статью следует написать. Читать текст может разработчик, выбирающий базу данных для проекта. А может и бухгалтер, который интересуется IT и изучает статью в обеденный перерыв.
Определив читателя, мы поймём, какие термины использовать без объяснения, а какие придётся развернуть. Профессионалу незачем рассказывать о различиях реляционных и нереляционных баз данных. Но новичку эти различия придётся объяснить. Если пишете текст для широкой аудитории, всегда измеряйте её знания по самому неподготовленному читателю.
Поймите желание и боль
Мы — люди — потребляем контент, только когда считаем его ценным. Когда он решает какую-то нашу проблему или приносит пользу. Поэтому статья должна быть написана для читателя: для решения его проблемы.
«Отличия реляционных БД от нереляционных» — плохой заголовок. Узнает читатель отличия, и что с того? Если мы пишем статью для начинающих разработчиков, хороший заголовок: «Как выбрать базу данных для интернет-магазина». Из него понятна польза: прочитаю и смогу выбирать базы данных правильно. Но это сработает только в том случае, если читатель уже знает, что такое базы данных.
Если читатель пока с базами данных не знаком, для него больше пользы в заголовке «Где хранить данные о товарах?». Заголовок всё ещё можно улучшить и сделать «кликбейтным», но важно, что он уже сформирован в категориях, знакомых читателю.
Определите цель
С аудиторией разобрались. С пользой — тоже. Можно переходить к написанию.
Хорошая статья всегда имеет продуманную структуру. Следует заранее определиться, о чём мы говорим сначала, о чём — потом. И только после этого приниматься писать.
Мы рекомендуем отталкиваться от цели технологии. Любая технология решает какую-то задачу. Поэтому главное — ответ на вопрос «Зачем нужна эта технология?»
JavaScript нужен, чтобы делать сайт интерактивным.
Node.js нужна, чтобы программировать сайт на JS.
Промисы нужны для работы с асинхронным кодом.
Тут важен контекст, в котором мы рассказываем о технологии.
Контекст № 1: научить программировать сервер на Node.js. В этом случае цель — разработка сервера.
Контекст № 2: рассказать историю создания Node.js. В таком случае цель Node.js — асинхронная обработка запросов. То есть то, для чего Node.js была создана.
Поставьте задачу
После того как определили цель технологии, переходим к задаче, которую эта технология решает.
Node.js нужна для разработки сервера. Значит, задача — развернуть сервер на ноде.
Express нужен для быстрого написания кода, который будет просто поддерживать. Задача: развернуть сервер на Express.
DOM нужен для управления элементами на странице. Значит, нужно собрать область сайта из JavaScript.
Тут пригодится опыт автора — только разработчик понимает, какую задачу можно реализовать технологией.
Напишите вступление
Когда стало ясно, зачем нужно конкретное понятие, о нём остаётся рассказать. Тут на помощь приходит принцип пирамиды Минто.
  1. Определите ситуацию:
    • нужно отрисовать десять тысяч карточек товаров;
    • вы изучали, как обрабатывать запросы пользователя;
    • в прошлый раз мы говорили о массивах.
  2. Опишите развитие ситуации. Этот пункт создаёт конфликт. Обычно он начинается со слова «но»:
    • Код для отрисовки карточек можно скопировать, но что делать, если мы не знаем заранее, сколько их будет?
    • Когда видов запросов к серверу немного, мы можем всё написать в app.js, но что делать, когда у нас миллион страниц?
    • Массивы отлично подходят для однотипных данных. Но как нам сохранить в них пользователя? Индекс элемента ничего не говорит нам о значении.
  3. И наконец — дайте разгадку. Это то понятие, которое мы хотим объяснить.
    • когда элементов очень много, на помощь приходят циклы;
    • чтобы код не превратился в ужас и кошмар, его разбивают на модули;
    • сложные структуры данных удобно хранить в массивах.
Вступление готово. Теперь у читателя есть интерес: он понимает проблему, потому что она основана на его знаниях и опыте. И у него есть решение — нужно только прочитать дальше.
Напишите основную часть
Опять разбиваем понятие на составляющие. Тут сложно дать чёткие советы, потому что всё очень сильно зависит от темы. Главное — придерживаться трёх правил:
  • Всегда понятно, зачем это читать. Чтобы проверить, выполняется ли это правило, после каждого предложения задавайте себе вопрос: «К чему это я?» Если вы не можете найти ответ, не сможет и читатель. Как следствие — потеряет фокус и интерес.
  • От простого к сложному. Мы никогда не пользуемся понятиями, о которых пользователь не знает.
  • Объяснения и примеры небольшими порциями. Мы в Яндекс.Практикуме используем выражение «образование в стиле stack overflow». Это означает «дать большой кусок кода и потом объяснять, что там происходило». Так делать нельзя. Автор может пользоваться этим как отправной точкой для объяснения очередной части. Но для читателя всё должно быть выстроено так: сначала нам нужно сделать вот это, для этого мы... Потом необходимо сделать вот это вот, потому что... Это делается...
Напишите заключение
Читателю нужно осознать, чтó он прочёл. В конце статьи вернитесь к задаче и повторите, как вы её решали. Фактически, заключение — это краткий пересказ всего текста.
Ещё сюда стоит добавить зачин для следующей статьи: «Мы делали вот это так, но как же быть с вон тем. А вот об этом — в следующей серии».
Следите за стилем
Самое важное — читайте текст вслух. Послушайте, насколько легко читается текст, не сбиваетесь ли вы по интонации. Текст с хорошим синтаксисом льётся, читать его легко. Дайте текст своим друзьям, супругам, родителям. Короче, тем людям, которые пока текст не видели. И попросите их прочитать вслух. Если они постоянно сбиваются — с синтаксисом что-то не так.
Верный способ сделать хороший синтаксис — писать просто. Лучше всего работают предложения, в которых есть подлежащее-существительное и сказуемое-глагол.
  • Дед ударил молотком по пальцу.
  • Анюта встала и подняла подбородок.
Причастные обороты, вводные конструкции, деепричастия, уточнения — убивайте. Если можете, конечно.
Также важно правильно оформить абзац. Помните: один абзац — одна мысль. Причём первое предложение абзаца эту мысль должно выражать. Все последующие предложения аргументируют или поясняют первое. Так что всегда проверяйте, связаны ли они с самым первым.
Примените на практике
Помните, что самое важное — писать. Невозможно научиться писать по курсам, рассылкам, YouTube или статьям вроде этой. Умение писать приходит только с практикой.
Но рассылки, статьи и курсы очень помогают. Развивайтесь как автор: изучайте принципы повествования и драматургии, читайте хорошие тексты и старайтесь понять, как они составлены. И вы станете писать ещё лучше, чем сейчас. Желаем удачи!
Автор: Максим Курепов, редактор в Яндекс.Практикум
Tags:
Hubs:
Total votes 19: ↑15 and ↓4+11
Comments8