Перейти к содержимому
M
Все статьи
Практика 7 мин чтения

ТЗ на плагин Moodle: как поставить задачу программисту, чтобы получить то, что нужно

Как составить техническое задание на плагин Moodle: разделы, примеры формулировок, критерии приёмки и частые ошибки постановки. Для заказчика без опыта в PHP.

Как составить техническое задание на плагин Moodle: разделы, примеры формулировок, критерии приёмки и частые ошибки постановки. Для заказчика без опыта в PHP.

Плагин для 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. Какие фильтры нужны: группа, курс, период, статус.
  2. Какие строки считаются: все ли студенты или только активные, учитывать ли отчисленных.
  3. Как считать итоги: среднее, сумма, процент и по какому правилу округлять.
  4. Кто видит отчёт и видит ли чужие группы.
  5. Как называется файл и куда сохраняется.

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

Критерии приёмки: как проверить результат

Хорошие критерии пишутся до начала работы и содержат действие и ожидаемый результат. Образец для отчёта:

№ДействиеОжидаемый результат
1Методист выбирает группу и нажимает «Сформировать»Скачивается файл Excel с колонками по образцу
2Выбор группы, где нет студентовПонятное сообщение, а не пустой файл или ошибка
3Преподаватель открывает страницуДоступ закрыт, отображается сообщение о нехватке прав
4Студент с оценкой в нескольких курсахСтрока не дублируется, значение берётся по правилу из ТЗ
5Группа из 300 человекФайл формируется без ошибки времени выполнения

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

Типичные ошибки постановки

ОшибкаК чему приводитКак исправить
Нет версии Moodle и PHPПлагин не устанавливается или падаетУказать версии в разделе «Среда»
Только цель без сценариевКаждый понимает по-своемуРасписать шаги пользователя
Нет образца документаКолонки и формулировки не совпадаютПриложить образец
Не указаны ролиОтчёт видят те, кому нельзяПеречислить роли и права
Нет границ работыРасширение объёма без согласованияВыписать, что в работу не входит
Не описаны большие объёмыРаботает на тесте, виснет на реальных данныхУказать число пользователей и записей

Пример короткого ТЗ для небольшой доработки

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

РазделСодержание
ЦельМетодист получает список слушателей курса одним действием без ручного копирования
СредаMoodle 4.5, PHP 8.3, тема Boost, плагин зачисления «Ручное» и «Когорты»
РолиМетодист (системная роль) — доступ ко всем курсам; преподаватель — не видит кнопку
Поля файлаФИО, адрес почты, группа (из когорты), дата зачисления, дата последнего входа в курс
ОграниченияЯдро не меняется; другие форматы, кроме Excel, не нужны; персональные данные в журнал событий не пишутся
ПриёмкаКурс на 5 слушателей и курс на 300 слушателей; роль без права получает отказ
ПередачаАрхив плагина, исходный код в репозитории заказчика, одна страница инструкции

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

Что делать с изменениями по ходу работы

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

Что исполнитель вправе спросить у вас

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

Что делать, если ТЗ писать некогда

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

Нужна помощь с Moodle?

Опишите задачу — расскажу, как решить её конкретно в вашем случае. Свяжитесь — разберём вместе.