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