Ранее я уже рассказывал о полезных свойствах такого документа как техническое задание ^[1]. В этот раз я расскажу о том, как я пишу подобные документы.

Я пробовал когда-то создавать проектную документацию по ГОСТу ^[2], но данный подход оказался «несовместим» с реальной жизнью. В итоге я пришел к менее формальному решению и использую последние годы следующую структуру этого документа:

 Заголовок: Техническое задание на разработку
 Изменения
 Основные положения
 Release Notes
 Терминология и Соглашения
 Что необходимо сделать
 Идеи и дополнения

где,

Изменения

Список значимых изменений в документе. Каждая запись начинается с даты и версии документа. Изменения отсортированы в порядке устаревания.

    =CHANGES
    Jan 22th 2012(v0.3)[zag]   Изменения в алгоритме работы crawler (+ определение качества фильма). 
    Jan  6th 2012(v0.2)[zag]   Основные функциональные блоки.
    Dec 24th 2011(v0.1)[zag]   Начальная версия

Основные положения

Здесь описывается идея и общий результат. Данный раздел начинается с фразы: «Требуется разработать ...».

  =head1 Основные положения

   Требуется разработать систему размещения рекламных объявлений 
   на виджетах со следующими возможностями:

  =item Создание и редактирование рекламных компаний
  =item Отображение рекламы на виджетах
  =item Сбор статистической информации (показы, переходы)

Описание целей сопровождаются снимками прототипов (или набросками от руки).

Release Notes

Список задач, которые станут частью выпускаемых версий. Задачи формулируются в виде строк, которые будут затем перенесены в Release Notes к каждой версии.

Например:

 =head1 Release Notes

 * Отображение рекламы на виджетах 
 * Рабочее место менеджера рекламных компаний ( управление рекламными компаниями 
   и просмотр статистики)
 * Регистрация отображения рекламных сообщений и переходов по ссылкам

Терминология и соглашения

Здесь полезно дать определение базовым терминам.

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

 =head1 Терминология и соглашения

 Термины, котороые появляются в контексте «Системы рекламных сообщений»:

 =defn Медиаплан
 реклмное объявление, которое ...
 =defn Карточка медиаплана
 форма отображения свойств медиаплана, содержащая ...

Что необходимо сделать ?

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

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

 =head1 Что необходимо сделать ?
 =head2 Общая структура

 Рассмотрим общую структуру, на которой выделим составные части и связи между ними:

     РИСУНОК ОБЩЕЙ СТРУКТУРЫ

 , где (1) - web интерфейс (рабочее место менеджера рекламных компаний)

 =head3 Рабочее место менеджера рекламных компаний

Идеи и дополнения

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

Обычное содержимое этого раздела следующее:

  =head1 Идеи и дополнения

  ___________________________________________________
  ___________________________________________________
  ___________________________________________________
  ___________________________________________________
  ___________________________________________________

За основу такой структуры ТЗ, я взял документ из какого-то зарубежного блога, посвященного тематике разработки Web проектов. Возможно подойдет определение «функциональная спецификация», но как бы то ни было, наличие этого документа облегчает жизнь всем.