Плагин для Moodle можно заказать за один разговор, но получить из этого разговора то, что нужно, удаётся редко. Причина почти всегда одна: заказчик знает, зачем ему результат, а программист знает, как его сделать, и между этими двумя знаниями нет документа. Ниже я показываю структуру технического задания, которой пользуюсь сама, с примерами формулировок. Подойдёт для плагина, отчёта, интеграции и небольшой доработки Moodle.
Зачем нужно ТЗ, если задача кажется простой
Фраза «сделайте кабинет слушателя» у разных людей вызывает разные картинки. Кто-то представляет страницу с курсами, кто-то систему загрузки документов с проверкой методистом, кто-то лента уведомлений. Без описания исполнитель выбирает ближайший вариант, а заказчик узнаёт об этом при приёмке. Документ нужен, чтобы разногласия возникли до начала работ, когда они стоят дешевле всего.
ТЗ защищает обе стороны: заказчика от неожиданного результата, исполнителя от бесконечных правок. Объём документа зависит от задачи. Для небольшого отчёта хватит страницы, для личного кабинета — нескольких.
Разделы технического задания
| Раздел | Что написать | Пример формулировки |
|---|---|---|
| 1. Цель | Зачем это нужно, какую проблему решает | Методисты вручную собирают сведения о прохождении курсов; нужно сократить это до одного действия |
| 2. Среда | Версия Moodle, PHP, база, тема, ключевые плагины | Moodle 4.5 LTS, PHP 8.3, PostgreSQL, тема Boost |
| 3. Пользователи и роли | Кто пользуется и что им разрешено | Роль «Методист» видит все группы; преподаватель только свои курсы |
| 4. Сценарии | Что делает пользователь по шагам | Методист открывает страницу, выбирает группу и период, нажимает «Сформировать» |
| 5. Данные | Откуда берутся и куда записываются | Оценки из журнала Moodle, список студентов из когорты; новые данные не сохраняются |
| 6. Результат | Вид и формат: экран, Excel, PDF, письмо | Файл Excel с колонками по образцу в приложении |
| 7. Ограничения | Чего делать нельзя, что не входит в работу | Ядро не изменяется; интеграция с 1С в этот этап не входит |
| 8. Приёмка | Как проверим, что всё сделано | Пять сценариев на тестовой копии (см. ниже) |
| 9. Передача | Что получаем в конце | Исходный код в репозитории, краткая инструкция, архив плагина для установки |
Если вы сомневаетесь в разделе «Среда», посмотрите страницу «Информация о сайте» в администрировании Moodle или спросите администратора. Про выбор версии для новой системы я писала в материалах про обновление: плагин делают под конкретную ветку, и несовпадение сказывается при установке.
Как описывать сценарии
Сценарий — это история пользователя, записанная короткими шагами: кто, что делает, что получает. Хорошо работает формат «Если..., то...». Например:
- Если слушатель загрузил документ, то методист видит его в очереди проверки со статусом «Ожидает».
- Если методист отклонил документ, то слушателю приходит уведомление с комментарием.
- Если документ принят, то он блокируется от замены, а у слушателя в кабинете меняется отметка.
Такая запись показывает не только основную линию, но и ветки, в которых чаще всего прячутся ошибки. Именно по ним в моих проектах уточняется больше всего деталей: например, что происходит, если слушатель загрузил файл неподходящего типа или превысил размер.
Как поставить задачу на отчёт или документ
Отчёты и печатные формы заказывают чаще всего. Лучший способ описания — образец. Приложите файл Excel или бланк, который сейчас заполняется вручную, и обозначьте у каждого поля источник данных. Для электронной зачётной книжки, которую я делала для нескольких колледжей и центра ДПО, образец документа решил больше вопросов, чем десять страниц текстовых описаний. Подробнее о документах и ведомостях — на странице печатных форм.
В описании отчёта укажите:
- Какие фильтры нужны: группа, курс, период, статус.
- Какие строки считаются: все ли студенты или только активные, учитывать ли отчисленных.
- Как считать итоги: среднее, сумма, процент и по какому правилу округлять.
- Кто видит отчёт и видит ли чужие группы.
- Как называется файл и куда сохраняется.
Если отчёт делается под требования регламента или проверяющих, отдельно приложите нормативный документ; такие случаи я собрала на странице разработки отчёта под регламент.
Критерии приёмки: как проверить результат
Хорошие критерии пишутся до начала работы и содержат действие и ожидаемый результат. Образец для отчёта:
| № | Действие | Ожидаемый результат |
|---|---|---|
| 1 | Методист выбирает группу и нажимает «Сформировать» | Скачивается файл Excel с колонками по образцу |
| 2 | Выбор группы, где нет студентов | Понятное сообщение, а не пустой файл или ошибка |
| 3 | Преподаватель открывает страницу | Доступ закрыт, отображается сообщение о нехватке прав |
| 4 | Студент с оценкой в нескольких курсах | Строка не дублируется, значение берётся по правилу из ТЗ |
| 5 | Группа из 300 человек | Файл формируется без ошибки времени выполнения |
Пятый пункт полезен для любых задач: он проверяет поведение на большом объёме, а не на примере из трёх записей. Вопросы приёмки я подробнее разбирала в статье про чек-лист приёмки.
Типичные ошибки постановки
| Ошибка | К чему приводит | Как исправить |
|---|---|---|
| Нет версии Moodle и PHP | Плагин не устанавливается или падает | Указать версии в разделе «Среда» |
| Только цель без сценариев | Каждый понимает по-своему | Расписать шаги пользователя |
| Нет образца документа | Колонки и формулировки не совпадают | Приложить образец |
| Не указаны роли | Отчёт видят те, кому нельзя | Перечислить роли и права |
| Нет границ работы | Расширение объёма без согласования | Выписать, что в работу не входит |
| Не описаны большие объёмы | Работает на тесте, виснет на реальных данных | Указать число пользователей и записей |
Пример короткого ТЗ для небольшой доработки
Чтобы разделы из таблицы не казались громоздкими, вот как выглядит сокращённое задание на реальную по типу задачу: добавить кнопку выгрузки списка слушателей курса в Excel для роли «Методист».
| Раздел | Содержание |
|---|---|
| Цель | Методист получает список слушателей курса одним действием без ручного копирования |
| Среда | Moodle 4.5, PHP 8.3, тема Boost, плагин зачисления «Ручное» и «Когорты» |
| Роли | Методист (системная роль) — доступ ко всем курсам; преподаватель — не видит кнопку |
| Поля файла | ФИО, адрес почты, группа (из когорты), дата зачисления, дата последнего входа в курс |
| Ограничения | Ядро не меняется; другие форматы, кроме Excel, не нужны; персональные данные в журнал событий не пишутся |
| Приёмка | Курс на 5 слушателей и курс на 300 слушателей; роль без права получает отказ |
| Передача | Архив плагина, исходный код в репозитории заказчика, одна страница инструкции |
Такой документ можно составить за час, и он снимает почти все типичные недопонимания. Заметьте, что в нём нет технических деталей реализации: как именно писать код, определяет исполнитель. Заказчик отвечает за «что» и «для кого», исполнитель за «как».
Что делать с изменениями по ходу работы
Требования почти всегда уточняются в процессе, потому что, увидев результат, заказчик понимает, чего ему ещё не хватает. Это нормально, если изменения проходят через простую процедуру. Я записываю каждое уточнение одним сообщением: что меняется, что это значит для объёма и сроков, согласие заказчика. Небольшие правки входят в задачу, крупные оформляются как отдельный этап. Так спорный вопрос «это входило или не входило» превращается в обычное чтение записей.
Что исполнитель вправе спросить у вас
Хороший программист задаст вопросы, на которые вы, возможно, не думали отвечать заранее: что делать с отчисленными студентами, как обрабатывать повторное зачисление, нужно ли хранить историю изменений, на каком языке должны быть сообщения об ошибках. Не воспринимайте это как придирки. Каждый такой вопрос превращает будущую неприятность в строку документа. Выделите время на ответы и фиксируйте их в ТЗ, пока их помнят все участники. Если на вопрос нет ответа, договоритесь, кто и когда его даст, и не начинайте связанную часть работы до этого момента.
Что делать, если ТЗ писать некогда
Тогда начните с трёх вещей: образца результата, списка ролей и двух-трёх сценариев. Остальное я уточню с вами в разговоре и запишу в короткий документ, который утверждается письменно. Если задача связана с интеграцией или отчётом, опишите её на странице разработки плагинов: я задам вопросы, соберу из ответов ТЗ и сразу скажу, какие места самые рискованные.
Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.