К содержимому
← Вернуться в блог

ТЗ, help и мануал: как описать требования, функции и последовательность действий

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

Если границы размыты, страдают все. Подрядчик получает документ, из которого нельзя понять объём работ. Пользователь открывает справку и находит там пересказ кнопок вместо решения своей задачи. Сотрудник читает инструкцию и застревает на шаге, который автор считал очевидным. Поддержка тем временем отвечает на одни и те же вопросы, а заказчик и исполнитель спорят о том, что считалось частью работы.

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

Три документа — три задачи

Разделение полезно держать в голове ещё до того, как появится первый абзац текста. У каждого документа свой читатель, свой момент чтения и свой результат.

Документ Кому адресован Главный вопрос читателя Обязательные блоки
ТЗ исполнителю: разработчику, дизайнеру, подрядчику Что нужно сделать и как поймут, что готово? цель, функции, ограничения, критерии приёмки, границы работ
Help / справка пользователю, который уже работает с продуктом Как решить мою задачу или ошибку? сценарий, шаги решения, причины сбоя, связанные статьи
Мануал новичку или сотруднику, осваивающему процесс Что делать по порядку, чтобы получить результат? условия старта, шаги, ожидаемый результат, действия при сбое

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

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

Мануал читают один раз, перед первым запуском процесса, или возвращаются к нему при сбое. Он отвечает на вопрос «что делать по порядку», а не «что вообще бывает». Один и тот же продукт может требовать всех трёх документов, и это нормально: они не дублируют, а дополняют друг друга.

Отдельная ловушка — пытаться закрыть одним текстом две задачи. Например, отдать пользователям ТЗ вместо инструкции или вставить в мануал внутренние требования к производительности. Читатель в таком случае получает лишнее и не получает нужное. Ещё один частый сбой — когда ТЗ пишут «на будущее», без конкретной задачи, и документ превращается в описание пожеланий, которые невозможно ни оценить, ни принять.

ТЗ: требования, функции и критерии приёмки

Техническое задание — это документ договорённости, а не литературное произведение. Его ценность измеряется не объёмом, а тем, сколько вопросов исполнителя он снимает до старта. Чем раньше обнаружено расхождение в понимании, тем дешевле оно обходится обеим сторонам.

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

Как собирать требования

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

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

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

Функциональные и нефункциональные требования

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

Нефункциональные требования описывают условия: права доступа, совместимость, язык интерфейса, объём данных, нагрузку, журналирование, поддержку. Именно здесь чаще всего появляются размытые слова. «Работает быстро», «удобно на телефоне», «поддерживает большие файлы» — не требования, пока не согласованы измеримые границы. Если точные значения не заданы заказчиком, их обсуждают и фиксируют числами, а не оставляют на усмотрение исполнителя.

Представим ситуацию: в личном кабинете нужен экспорт заявок. Функциональное требование — «пользователь выгружает список своих заявок в файл». Нефункциональные — «выгрузка доступна только владельцу данных», «файл открывается в табличном редакторе», «при большом объёме показывается ход выполнения». Конкретные ограничения по объёму и времени согласуются отдельно и записываются в документ.

Если речь идёт о разработке, полезно заранее договориться, как каждая функция будет проверяться: это снижает риск спора на приёмке. Подробнее о таком подходе — в материале о программировании и реализации функций по требованиям с проверкой результата.

Критерии приёмки и границы работ

Критерий приёмки — это наблюдаемая проверка, а не оценка. Формулировка «сделано качественно» ничего не проверяет. Формулировка «при попытке войти с неверным паролем показывается сообщение об ошибке, повторный вход с верным паролем открывает личный кабинет» проверяется за минуту.

Границы работ защищают обе стороны. Явный список «что не входит» избавляет от спора, в котором одна сторона считала перенос данных частью задачи, а другая — отдельной работой. Там же описывают порядок изменений: как фиксируются новые требования, кто их согласует, как это влияет на сроки и объём.

Полезно заранее назвать, что будет считаться результатом: работающая функция, документ, макет, набор файлов, доступ к среде. Пока результат не описан предметно, приёмка превращается в переговоры о вкусах.

Каркас ТЗ, который удобно адаптировать под свою задачу:

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

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

Help-раздел: ответы на вопросы пользователя

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

Первый принцип — одна статья отвечает на один вопрос. Если в заголовке стоит «Работа с заявками», читатель не понимает, найден ли ответ. Если заголовок звучит как «Как изменить адрес доставки в уже оформленной заявке», совпадение с запросом почти гарантировано.

Формат «вопрос — ответ» и структура статьи справки

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

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

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

Отдельно про тон. Фразы «просто нажмите», «очевидно, что», «как вы знаете» ставят читателя в неудобное положение, если у него не получилось. Нейтральное «нажмите», «выберите», «если этого пункта нет, значит…» работает лучше.

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

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

Мануал: последовательность действий без пропусков

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

Шаги, условия и результат

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

  1. Подготовка: перечислить, что нужно иметь до начала.
  2. Вход: куда зайти и под какими правами.
  3. Действие: один шаг — одно действие, с точным названием пункта меню.
  4. Проверка: как выглядит успешный результат.
  5. Действия при сбое: что проверить и куда обратиться, если результат другой.

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

Ещё одна частая проблема — шаги, которые невозможно выполнить буквально. «Настройте параметры под свои нужды» не говорит, какие параметры важны и что изменится. «Отметьте пункт «Уведомления», чтобы получать письма о статусе» говорит. Правило простое: если шаг нельзя повторить по тексту, текст нужно переписать.

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

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

Проверка документа перед передачей

Финальный этап занимает меньше времени, чем правки после старта. Пройдите текст глазами читателя и проверьте его по списку.

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

Типичные ошибки повторяются из проекта в проект. Слишком общий заголовок, из которого неясно, о чём текст. Смешение требований и инструкции в одном документе. Отсутствие границ работ в ТЗ. Пропущенное условие доступа в мануале. Справка, написанная языком разработчика. Устаревшие скриншоты. Ни одна из этих проблем не требует таланта — только внимания к читателю.

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

И последнее: не пытайтесь сделать документ исчерпывающим навсегда. Достаточно, чтобы он был точным на момент передачи и имел понятный порядок обновления. Если по ходу работы выясняется, что требование понято иначе, это фиксируют в документе, а не в переписке, иначе через месяц никто не вспомнит договорённость.

Частые вопросы

Чем ТЗ отличается от мануала?

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

Что обязательно должно быть в техническом задании?

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

Сколько статей должно быть в справке help?

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

Можно ли объединить help и мануал в один документ?

Технически можно, но читателю будет сложнее. Справка отвечает на точечный вопрос, мануал ведёт по процессу целиком. Если продукт небольшой, допустим единый раздел документации с разными типами статей, но смешивать в одной статье обзор процесса и решение конкретной ошибки не стоит.

Кто пишет ТЗ — заказчик или исполнитель?

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

Как часто обновлять инструкции и справку?

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

Нужны ли скриншоты в мануале?

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