Пишем спецификации. Часть 1. Инструменты — начинаем с простого

Итак, наконец-то мы решили начать писать спецификации. Поскольку сам процесс для нас новый, пускай хотя бы инструменты будут привычными.
Что мы хотим от инструмента? Пожалуй, все требования сводятся к одному слову — удобство. Ведь нужно иметь очень веские причины, чтобы заниматься чем-то, если это делать неудобно. А ведь нам хочется, чтобы наши коллеги получали удовольствие от написания спецификаций. Как, например, от программирования.

Лично у меня требований немного:

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

Вариант 1. Microsoft Office.
На первый взгляд, простое решение. Мы уже умеем пользоваться Ворд-ом, он установлен у всех программистов, так что проблем быть не должно.

Чтобы было легче найти нужную спецификацию, надо для них завести централизованное место хранения. Создадим на сервере папку ПРОЕКТЫ с подпапками по числу проектов. Сюда и будем складывать наши документы.

Со временем мы придумали шаблон оформления типовой спецификации. Нет, это не стандартное содержание из 20 пунктов, которые должны быть в любой спецификации. Боже упаси. Мы описали стили оформления разных смысловых частей:

• Заголовок спецификации: тема, автор / дата / рецензент
• Исходная формулировка / требования от заказчика
• Примечания для тестировщиков
• Примечания для разработчиков – когда в тексте функциональной спецификации нужно на чем-то заострить их внимание. Если же это целиком техническая спецификация, например описание реализации какой-то хитрой функции на сервере, или всякой там архитектуры, то используем обычный стиль.
• Сценарий.

Полезная вещь оказалась. Документы стали такими весёлыми, разноцветными, читать приятно. И можно сразу найти нужную часть, даже не вчитываясь в текст, только по внешнему виду.

Чуть позже стало понятно, что нам нужны перекрестные ссылки из одного документа на другой. Благо в Ворд-е есть относительно удобный механизм для этого. Можно делать ссылки и внутри документа, и между документами. Со временем стали появляться документы – порталы, состоящие в основном из ссылок на другие документы.

Иногда (точнее, довольно часто) надо вставить в спецификацию какой-нибудь эскиз интерфейса, или скажем UML-диаграмму. Их мы рисуем в Визио, а потом вставляем в спецификацию. Вопрос – где хранить сами визиевские файлы? Давайте придумаем хитрые правила – для хранения связанных файлов будем создавать папку с именем, как у документа, и в нее класть дополнительные материалы.

Итоги:

• За полгода работы над одним из наших проектов было порождено порядка тридцати полновесных спецификаций. Их писали аналитик, ведущий разработчик, и некоторые рядовые разработчики.
• Нам потребовалось:
  
  • программы из пакета MS Office, по числу пишуших спецификации.
  • общедоступная папка на сервере для хранения документов.
• Разработаны правила оформления и хранения спецификаций.

Плюсы:
Пологая учебная курва ((с) Голубицкий). Для запуска процесса не требуется никаких усилий, кроме волевых. Все необходимые инструменты – офисные программы и сетевой диск – как правило, уже имеются. Сохраняются все навыки работы с документами (если у кого были).

Минусы:

• Затруднена совместная работа. Если кто-то открыл спецификацию, больше никто в это время ее изменять не может.
• Нет истории изменений. Сложно понять, что изменилось в спецификации с момента твоего последнего чтения. Даже с помощью продвинутых средств Ворда – рецензирования, можно отслеживать только одну итерацию правки документа. Но и при этом документ становится нечитаемым из за подчеркиваний-перечеркиваний и линий-примечаний.
• Затруднен поиск. Сложно найти нужную спецификацию, и в ней – нужную часть. Необходимо помнить, хотя бы приблизительно, как называется документ, и потом пытаться найти его среди пятидесяти его товарищей. Да, казалось бы, в windows есть поиск по файлам. Но нужно сделать кучу шаманских действий, чтобы он начал искать по офисным документам. А потом повторить это на всех тридцати компьютерах разработчиков.

Резюме:
Описанный инструментарий вполне достаточен, когда вы только начинаете пробовать свои силы в специфицировании. Его можно использовать в очень небольших проектах с числом разработчиков около пяти. Если же у вас несколько проектов, несколько команд, и главное, вы уже вкусили прелестей спецификаций и вам хочется большего, то вам нужен более продвинутый инструмент. Для себя мы нашли его в Вики.
(см. Часть 2. Вики — всё под рукой)