Ясные формулировки — Как писать классные тексты

Распутывайте порядок действий
- Деепричастия
- Причастия
Меняйте скрытое действие на открытое
Показывайте главного героя
Выводы и практические советы

Авторов образовательного контента в IT ценят за знания из их профессиональной сферы. Хорошему автору-эксперту нужен разнообразный опыт, широкий стек, глубокое понимание технологий.

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

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

Распутывайте порядок действий

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

Разберем каждый оборот подробнее.

Деепричастия

Они отвечают на вопрос «Что сделав?» или «Что делая?» и обозначают дополнительное действие. Посмотрите на этот пример:

Указав после имени функции круглые скобки, поместив в них параметры и отделив каждый из них запятой, можно вызвать функцию

Здесь всего один глагол, который указывает на одно действие — «вызвать функцию». Остальные действия скрыты в деепричастиях — «указав», «поместив» и «отделив». На самом деле в предложении упоминается четыре действия, но из-за деепричастий студент заметит только одно из них. Из-за этого он может неправильно понять порядок действий.

Чтобы студенту было проще проследить последовательность действий, избавимся от деепричастных оборотов и заменим их на глаголы:

Чтобы вызвать функцию, укажите после ее имени круглые скобки, поместите в них параметры и отделите их запятой

Причастия

Они похожи на прилагательные — отвечают на вопрос «Какой?». При этом они описывают действие и главного героя в скрытой форме. Например:

Параметры функции, не отделенные запятой, приведут к ошибке

Из этого предложения студент точно поймет, что в каких-то случаях «параметры функции приведут к ошибке». Ему будет сложно разобраться в деталях:

Кто должен отделять параметры запятой?
Это происходит автоматически или надо делать это вручную?
А если отделить параметры, ошибка произойдет или нет?

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

Если не отделить параметры функции запятой, то программа выдаст ошибку

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

Меняйте скрытое действие на открытое

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

Рассмотрим такой пример:

Я выбежал на лестницу, но врезался в кого-то и упал, в итоге пролетел пару метров и сломал руку

Читателю легко представить, что происходило и в каком порядке. В этом предложении очень много глаголов, поэтому в нем чувствуется динамика. Обратите внимание, что в этом примере нет слов «быстро» или «стремительно» — но мы все равно чувствуем, что события происходили быстро и стремительно.

А теперь заменим все глаголы действия на отглагольные существительные:

Когда я был в процессе быстрого бега по лестнице, произошло столкновение с другим человеком, после которого последовало падение с высоты в пару метров и перелом руки

По этому предложению уже сложнее выстроить цепочку событий и прочувствовать динамику. Но есть еще один побочный эффект:

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

Такой же эффект работает с техническими текстами и уроками. Посмотрим на примере:

Параметры — это информация, которая передается в функцию при вызове. На основе этой информации посредством функции происходят вычисления и выдача результата.

При создании переменной result интерпретатор получает указание на вызов функции len() и запись возвращенного результата.

Одно из постоянных свойств функции — это возврат результата своей работы. Запись len('Hello!') означает вызов функции с именем len и передачу параметра 'Hello!'.

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

Поменяем в нем существительные на глаголы с активным действием:

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

Давайте создадим переменную result и укажем интерпретатору: «Вызови функцию len() и запиши результат, который вернется».

Функции всегда возвращают результат своей работы. Запись len('Hello!') означает, что мы вызвали функцию с именем len и передали параметр 'Hello!'.

Этот отрывок больше похож на урок: наставник и студент вместе создают переменную, дают команду и получают результат.

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

Показывайте главного героя

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

Эту мысль часто объясняют на таком примере:

Уважаемые жители! С 1 января по 31 января в вашем доме будут отключены вода и электричество. Дополнительную информацию об отключении можно получить по телефону +7(900)-000-00-00. Ваши обращения рассматриваются в течение 20 рабочих дней.

В этом тексте есть манипуляция. Грамматика скрывает подлежащее — главного героя, который и вызвал все эти неудобства:

Грамматика

Пример

Скрытая информация

Пассивный залог

Будут отключены вода и электричество

Сами по себе, мы не при делах

Модальный глагол

Информацию можно получить по телефону

А можно и не получать, лучше вообще не звоните нам с жалобами

Возвратный глагол

Обращения рассматриваются

Сами по себе, мы не виноваты в таких сроках

Попробуем заменить все канцелярские формулировки на глаголы действия:

Уважаемые жители! Мы решили отключить воду и электричество в вашем доме на весь январь. Если вам это не нравится, позвоните по телефону +7(900)-000-00-00 — мы ответим примерно через месяц.

Пример с глаголами стал звучать грубее и честнее — такое объявление точно получит больше возмущенных откликов.

Такие приемы встречаются и в образовательных текстах, пусть и не выглядят так критично. Здесь другая проблема — они скрывают от студента важную информацию:

Грамматика

Пример

Вопросы студента

Пассивный залог

Эти правила работы с функциями использованы в стандартных библиотеках

Кем они использованы? Это заранее настроено и работает автоматически? Или мне нужно помнить об этих правилах?

Возвратный глагол

Эти правила работы с функциями используются в стандартных библиотеках

Кем используются? Мной, интерпретатором, самой функцией, программой, библиотекой или автором библиотеки?

Модальный глагол

Эти правила работы с функциями можно использовать в стандартных библиотеках

А можно ли использовать в нестандартных библиотеках? А можно ли не использовать эти правила вообще? А за пределами библиотек надо это использовать? Это обязательно?

Такие формулировки оставляют неясность. У студента может сложиться впечатление, что он не усвоил новые знания из урока.

Из этого он может сделать два неверных и неприятных вывода:

«Автор сам ничего не знает, и такими формулировками скрыл свои пробелы в знаниях»
«Для автора это слишком очевидно, поэтому он выбрал такие формулировки. Скорее всего, дело во мне. Мне никогда не освоить программирование, это слишком сложно»

Чтобы этих выводов избежать, лучше использовать активные глаголы и проговаривать все неочевидные подробности:

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

Такими формулировками мы дадим студенту самую полную информацию и фундаментальные знания.

Выводы и практические советы

В этом уроке мы изучили некоторые аспекты редактуры, которые часто встречаются в технических и образовательных текстах в IT. Чтобы ваши тексты были понятнее и удобнее для студента, используйте эти приемы:

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

Самостоятельная работа

Отредактируйте этот текст так, чтобы он стал понятным:

Деплой — процесс «разворачивания» веб-сервиса, например, сайта, в рабочем окружении. Для понимания деплоя необходимо разобраться с жизненным циклом кода. Разрабатываясь на рабочей машине разработчика, код приложения запускается в другом месте, называемом продакшеном. Но сначала добавленный в репозиторий код надо доставить до продакшена. В итоге код запускается на продакшене — деплой завершен.

Чтобы вам было проще работать над этим заданием, следуйте такому алгоритму:

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

Нажмите, чтобы увидеть ответ

Мы предлагаем такой вариант:

Деплоем называют процесс, при котором разработчики разворачивают веб-сервис или сайт в рабочем окружении. Чтобы лучше понять деплой, разберемся с жизненным циклом кода.

Сначала разработчик пишет код на своей рабочей машине. Затем он добавляет код в репозиторий. Далее разработчик доставляет код до среды запуска — она называется продакшен. На финальном этапе разработчик запускает код на продакшене.

Все эти действия привели к тому, что разработчик задеплоил сайт.