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

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

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

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

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

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

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

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

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

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

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

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

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

    Подробнее
    Реклама

    Комментарии 14

      +3
      Microsoft и так хорошо рекламирует свои продукты ;)
      А вариант 2 планировался? Или только вариант 1 и сразу выводы?
        0
        То что вы описали вполне возможно реализовать с помощью любого wiki-движка. При этом не будет проблемы поиска, которые вы описали.

        Хотя с другой стороны этот подход «несколько сложнее» в реализации =)))
          0
          … то вам нужен более продвинутый инструмент. Для себя мы нашли его в Вики.
            0
            Как раз хотел процитировать последний абзац. Рад, что дочитали до конца :)
            Вариант №2 таки планировался. Как раз про вики. Сейчас пишется.
          +1
          Инструмент — это, конечно, самое главное в создании спецификаций.
            0
            Затруднена совместная работа.
            Нет истории изменений.
            Настройте SVN. TortoiseSVN вполне прост в обращении и позволяет сравнивать документы внешними программами, обзор которых был недавно на 3dnews. На сколько помню, там нашлись довольно удобные именно для doc-файлов.
            Затруднен поиск.
            Лично у нас данную проблему решили установкой поиска от Яндекса на собственном домене. Правда, с индексацией doc-файлов возникли какие-то проблемы, но на сколько знаю, их удалось решить, хотя бы частично.
              0
              Проблема истории изменений doc-документов в том, что кроме самого Microsoft Word'а нет ни одной программы, которая бы могла правильно сравнить и отобразить изменения в файле :\
                0
                Сейчас перепроверил, и убедился, что TortoiseSVN doc-файлы сравнивает Word-ом ;)
                  0
                  Как раз это я и называю — задача затруднена. Не невозможна в принципе, а решается с помощью других инструментов, призванных компенсировать недостатки основного.

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

                  Но мы сделали только несколько шагов в этом направлении и свернули с половины пути. Мы начали с самых простых средств, которые могли себе представить. Потому что, как правильно заметил г-н. beskov, это лишь средства. А цель была шире — запустить сам процесс написания спецификаций. Как писать, что писать, и в последнюю очередь — в чем писать.

                  Научились (ну я надеюсь). При этом попутно мы поняли, а чего собственно, мы хотим от нашего идеального инструмента, что было удобно а чего не хватало. И эти знания послужили основой для следующего витка инструментария.
                  Сейчас это вики. Соответствующим образом настроенная под наши задачи. О чем скоро я надеюсь рассказать.
              0
              Заменяем «Microsoft Office» на «бумагу и карандаш», а «сервер» на «шкаф» и не видим разницы никакой в посте. Итого: выбранный вами инструмент вы не используете по назначению, аки микроскопом гвозди. А ведь Офис — это и Visio и Exchange, например.
                0
                1. Не всегда девелоперы дефолтны рядом со шкафом.
                2. Визио и эксчейндж не дефолтные части офиса.
                  0
                  Разница есть. Если плясать от моих требований к инструменту, то бумага и карандаш решают только одно — удобство правки. Удобство чтения (с моим-то почерком) страдает. не говоря уже о поиске.
                  0
                  При подготовке достаточно большого документа в MS Word (более 60 страниц) применение множества перекрестных ссылок в рамках одного документа приводит к тому, что часто после редактирования документа ссылки «слетают» и приходится снова заниматься вычиткой документа и проверкой что ссылки после обновления служебных полей будут указывать туда куда нужно.

                  Поэтому считаю что для составления перекрестных ссылок данный формат слабо подходит. Кроме того и функционал выбора ссылки очень неудобен, что приводит к большим потерям времени при форматировании документа.
                    0
                    Эта беда нас миновала. Мы принципиально следуем правилу не писать развесистых документов. Одна задача — один документ. 10 страниц для спецификации — уже слишком много. Средний объем спецификации — 5 страниц. При этом половина из них — это всякие рисунки: диаграммы классов или эскизы экранов.

                  Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                  Самое читаемое