Чтение ФТ — занятие непростое. Восприятие новой информации и её анализ требуют продолжительной концентрации и расходуют главный ресурс IT‑шника — внимание.
Если текст сложный, читатель спотыкается в нём и увязает, перечитывает по несколько раз, тратя время и ресурс внимания.

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

Добавить краткое описание

В некоторых ФТ на описание краткого решения проблемы отводится одно‑два предложения в самом начале. Обычно это что‑то вроде: «Необходимо сделать механизм авторизации». Затем в каждой главе читателя с разбега погружают в детали решения. Чтение таких ФТ как сборка пазла, в котором вместо итоговой картинки‑подсказки написано слово «пейзаж». Не имея общей картины, вникать в написанное трудно, и непонятно, к чему относить все детали, которые встречаешь в процессе чтения.

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

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

Без краткого описания
Лишние вопросы, которые требуют уточнений

С кратким описанием
Многие лишние вопросы не появляются

Добавить заголовки

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

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

Без заголовков
Много текста и всё те же лишние вопросы

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

Перевести на язык читателя

Иногда в ФТ встречается прямая речь заказчика с его терминами, оборотами и упоминанием его процессов. Например, описание проблемы и её решение. Чтобы понимать такой текст, надо знать специфику бизнеса. На практике её не все могут знать, вернее знать могут не только лишь все... ну вы поняли. Иногда проще перейти к описанию решения и понять проблему оттуда.

Как быть? ФТ и так являются переводом с языка заказчика на язык команды, и тут нужно идти до конца — переводить всё. А именно, рассказать, что слова заказчика значат применительно к системе. Если всё‑таки нужно зафиксировать проблему словами заказчика, оставьте абзац в оригинале, а ниже дайте перевод. Не забудьте подсказать читателю, где что.

Языком заказчика
不清楚

Языком читателя
Знакомые термины

Обозначить целевую аудиторию (ЦА)

В ФТ бывают части, которые написаны для определённых ролей в команде. Например, архитектура решения может быть не интересна продактам, дизайнерам или техническим писателям. Если не дать подсказку, они не сразу поймут, что читают то, что им не нужно.
В таком случае можно подсказать им об этом, указав целевую аудиторию текста. Правда, чтобы правильно обозначить ЦА, нужно хорошо знать роли читателей: как они читают требования, что для них важно, а что нет. Процесс получения этих знаний — тема отдельной статьи.

Похожий случай — непропорциональное смешивание ЦА. Например, в целой странице текста для backend‑разработчика скрыты несколько предложений, важных для остальной команды. Тут нужно пожалеть их время и продублировать эти предложения где‑то ещё. По сути это комбинирование пары предыдущих приёмов: мы добавляем краткое описание и переводим его на язык остальной части команды.

Когда не ясно, для кого текст
Читатель тратит время

Когда ЦА обозначена
Читатель не тратит время на ненужные части

Упростить многоуровневые списки

Многоуровневые списки — зло (простите, любители таких списков). Их используют, чтобы показать чёткую иерархию информации, что к чему относится. На деле читателю не хватает внимания держать в голове всю структуру, чаще всего он будет помнить только то, что было на один‑два уровня выше. А ориентирование в семиуровневых списках на всю страницу можно назвать «спортивным» и выдавать за это медали.

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

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

Большой многоуровневый список
Легко встретить, трудно понять и невозможно сориентироваться

Бывший многоуровневый список
Сплющен и разделен на части заголовками

Убрать лишнее описание текущей функциональности

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

Использовать простые обороты

Единственный в этом списке и самый эффективный совет по стилю письма. Есть заблуждение, что чем официальнее написан текст, тем он более «профессиональный», поэтому в ФТ встречаются фразы «обеспечение соответствию выполняемой программы». Воспринимать такие обороты трудно, потому что фильмы, книги и наша речь устроены по‑другому.

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

«Профессиональная» речь
Больше слов, сложные обороты

Разговорная речь
Меньше слов, привычные обороты

Вывод

Как это всё запомнить?

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

Рекомендации

Если вы только погружаетесь в тему упрощения текста, первое, о чём услышите — книга «Пищи, сокращайся» «Пиши, сокращай». В дополнение к книге — сайт glvrd.ru, там же на главной можно проверить текст на читаемость.

Так же могу посоветовать видео Юрия Куприянова и Антона Самарина.