Slider Background

февраля 2010

Пишем спецификации. Часть 2. Инструменты. Вики – всё под рукой.

Продолжаю разговор об инструментах, с помощью которых можно сделать такой сложный и непривычный процесс написания спецификаций простым, доступным и даже прикольным (см. Часть 1. Инструменты - начинаем с простого). Я уже давно подумывал о том, чтобы приспособить для этого вики.

Благодарности
На фестивале 404 меня очень заинтересовал доклад Константина Коломейца из Яндекса об использовании различных инструментов для командной работы. Еще более интересной и познавательной оказалась дальнейшая беседа и ответы на вопросы в уголке экспертов на уютном диванчике. Это стало тем толчком, который склонил чашу весов от долгих раздумий к активным действиям.

Вспоминаем требования к инструментам

  • Удобство чтения.
    С этим все просто. Всё, что необходимо, для того, чтобы прочесть спецификацию - это браузер. Навыки работы в браузере наверное есть у всех :)
  • Удобство поиска.
    Найти нужную статью в нашей вики можно двумя способами:
    1. Навигация / ссылки. На боковой панели (sidebar), а также на первой странице вики есть ссылки на все наши проекты, а на главной странице - еще и на описание наших внутренних процессов.
      На головной странице каждого проекта есть ссылки на все (или почти все) статьи по этому проекту. Это такая большая-большая страница, состоящая только из ссылок. Они разбиты по категориям (описание процессов, интерфейс пользователя, межсерверное взаимодействие и т.п.). Там даже есть ссылки на те спецификации, которых еще нет, но которые точно должны быть.
    2. Поиск. Сейчас используется родной поиск MediaWiki. (В интернете есть куча способов, как прикрутить тот или иной продвинутый поисковый движок. Но пока хватает и родного, для того чтобы по одному-двум ключевым словам найти нужную статью.)
  • История изменений. Встроенных средств вполне достаточно.
  • Совместная работа. Встроенных средств разрешения конфликтов - достаточно. При том что редактируя документ не целиком, а конкретный раздел, шансы на создание такого конфликта очень малы. У нас это случается не чаще раза в неделю.
  • Удобство собственно редактирования
    Начинается самое интересное. У меня была задача - сделать так, чтобы нашим коллегам ХОТЕЛОСЬ пользоваться нашим инструментом. Для этого нужно, чтобы простые и повседневные действия не требовали изучения, а делались привычным способом. Дальнейшее изучение инструментария (язык разметки, всякие расширения) должно приносить немедленную и ощутимую пользу - повышать скорость работы или предоставлять новые возможности.
    Ниже я поведаю о том, как я боролся за удобство редактирования.

Набираем инструментарий
1) Движок. MediaWiki
Движков вики много. Не рискну утверждать, что один чем-то лучше другого. Я выбирал подходящий нам.
Во-первых, он бесплатный. Переходя на вики, я не был 100% уверены, что это будет окончательным решением, поэтому рисковать, покупая какую-нибудь коммерческую систему, не хотелось. Тем более что на тот момент для меня (немножко утрирую) все вики были на одно лицо.
Во-вторых, язык реализации. PHP/MySQL. У нас уже были и такие сайты, и такие специалисты, и мы были готовы, если придется, что-нибудь подкручивать-подвинчивать.
В-третьих, большое количество всяких расширений.
Ну и наконец, громкое имя. Я надеялся, что этот движок будет достаточно надежен, раз уж он тянет википедию.

2) Редактор. WikEd + FCKEditor
Конечно, мне хотелось визивига. Любая новая система будет воспринята в штыки, если для работы с ней придется менять свои привычки. В данном случае такой привычкой была работа с текстами. Все умели работать в ворде. А заставлять аналитиков учить всякие языки разметки (пусть и очень простые, но не нужные им для выполнения их основной работы) мне не хотелось. За программистов я был спокоен. После html вики-разметка просто сказка.

FCKEditor - wysiwyg редактор. Похож на Ворд (вы уж простите меня, что я через слово поминаю его, но жизнь такая, что любой ИТ-шник умеет писать в ворде и если повезет, еще в чем-нибудь). Так вот, он похож на ворд. Включая горячие клавиши. Удобно работать с таблицами. Удобно делать ссылки на другие статьи - он сам предлагает на выбор несколько статей по введенному ключевому слову.
Но есть и минусы. Основной - работа с буфером. Вставлять в буфер форматированный текст он соглашается. А вот из буфера - фигушки. Только plain-text. Что неожиданно. Я вырезал абзац, хочу вставить его в начало документа - ан нет. Приходится выделять и тащить мышкой. Я уж не говорю про вставку из ворда (а как нам переносить наши старые спецификации?)
Второй большой минус - не показывается содержимое шаблонов и расширений синтаксиса. То есть видно, что какая-то фигня там внутри есть. Хочешь посмотреть какая - смотри в отдельном окошке. Это неудобно, поскольку у нас есть ряд типовых шаблонов для комментариев в тексте, описаний сценариев и примечаний.
Поэтому одного редактора нам оказалось мало.

WikEd. Полная противоположность. Имеет плюсы там, где у соперника минусы. Но и наоборот.
Минус - он не совсем wysiwyg. Это редактор вики-разметки. Он показывает жирное жирным, а курсивное курсивом, но при этом показывает и разметку. И соответственно, не показывает, что же у нас увидят читатели. Надо жать превью.
Плюс - это, пожалуй, лучший редактор для вики-разметки. Для тех, кто предпочитает её визивигу.
Плюс - возможность вставки из буфера форматированного текста. В частности - из ворда. С последующей конвертацией в вики-разметку.
Минус - он не работает в Internet Explorer. Неудобно, но не критично. Аналитики осваивают firefox. Хуже поклонникам Оперы. Они переходить на firefox не хотят.

Так и живем. Два редактора. Переключаемся из одного в другой, в зависимости от задачи. Первоначальный вариант документа удобно править в FCKEditor. В нем же - работать с таблицами. Окончательную разметку, а также вставлять примечания, удобнее в WikEd.

3) Экспорт. PDFBook + доработка напильником для выгрузки в Word.
Один из вопросов при внедрении вики был - а как нам согласовывать наши спецификации с заказчиком? Вики у нас находится в интрасети, и шансов выставить ее наружу нет никаких. Да и как заказчику писать свои замечания? Тоже учить вики-разметку? Не вариант.
Вариант - экспорт в какой-нибудь общечеловеческий формат. Вы будете смеяться, но это - ворд. PDF можно читать, можно распечатать, но заказчик уже ничего в нем не напишет и не исправит.

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

Мы немного доработали это расширение, и теперь оно же умеет создавать и документы Word.
Ссылки для вызова этого расширения мы добавили в sidebar, и теперь любую страницу можно сохранить в файле doc или pdf.

4) Эскизы экранных форм. Balsamiq Mockup
Это просто чудо. Замечательно простой и прикольный редактор для рисования эскизов UI. Именно эскизов, в отличие, скажем, от Визио. Результирующий рисунок выглядит, как набросок карандашом от руки. И в этом вся прелесть. Рисуя в Визио, эскиз выглядит почти как настоящий интерфейс, и волей-неволей хочется сделать <красиво>. А в Balsamiq Mockup нет такого искушения. Внимание разработчика и заказчика концентрируется на главном - общий дизайн формы, состав и расположение контролов. Не отвлекаясь на такие несущественные моменты, как цвета, шрифты, выравнивание элементов с точностью до пиксела и прочие красоты. Которые, как правило, в рамках проекта определяются style guide.
Еще одно удобство - большой набор строительных блоков - контролов. При этом сложные контролы (например, многоколоночная таблица или дерево) не сложнее простых (кнопок или меток).

Кто пробовал нарисовать в Визио дерево, меня поймет.
Засчёт всего этого скорость рисования интерфейса по сравнению с Визио возрастает в разы.
И наконец, самый главный плюс. Эта штука замечательно интегрируется с Вики. Редактор представляет собой AIR-приложение, которое выполняется прямо на странице вики. И эскиз в своем формате сохраняет также прямо в вики. На сайте разработчика предлагается вариант для xWiki. Но легкая доработка напильником позволила запустить ее и в MediaWiki.
И напоследок должен сказать - это единственное ПЛАТНОЕ расширение (из всех, используемых нами). Но оно того стоит.
Кстати, есть и десктопная версия. (Бесплатная, только каждые 5 минут предлагает купить себя). Её наши аналитики берут с собой, выезжая к заказчикам.

5) UML. PlantUML
С помощью специального синтаксиса прямо в тексте вики-страницы можно <рисовать> UML-диаграммы. А потом по этому текстовому описанию будет построен рисунок. 
    <uml>
       Alice -> Bob: Authentication Request
       Bob --> Alice: Authentication Response
    </uml>

Поддерживаются все типы диаграмм (в отличие от многих других бесплатных программ, которые знают только диаграммы классов и последовательности). Это, конечно, не инструмент серьезного UML-проектирования, с порождением исходного кода. Но вполне достаточно для иллюстрации проектных решений. Один рисунок стоит сотни слов.
Неожиданно для меня, с появлением этого расширения UML прижился в нашей фирме. До этого были попытки рисовать разные диаграммы в визио. Но это делалось как-то через силу, без удовольствия. Думаю, потому что визио слишком строгий и требовательный. А PlantUML наоборот, прощает многое, сам старается угадать, что имелось в виду. И потому с ним приятно работать. Моих коллег как подменили. Все внезапно полюбили UML, чему я безумно рад.

6) Расцветка синтаксиса. SyntaxHighlight GeSHi
Во многих спецификациях мы, наряду с диаграммами, сразу набрасываем какой-то код. Хочется, чтобы он выглядел понятно и привычно, как в среде разработки. В этом нам помогает расширение для подсветки синтаксиса. В комплекте идет поддержка кучи языков, мы и не пользуемся всеми ими. Для своего любимого Delphi я немножко подкрутил настройки, чтобы выглядело более похоже на IDE.

Выводы
При правильной настройке вики становится замечательным инструментом для написания (хранения \ поиска \ чтения) спецификаций.
Такой общий блокнот+карандаш, в который можно писать при любом удобном случае. Так мы и стараемся поступать. Знаешь что-нибудь - быстрее запиши в вики, пока не забыл.

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

Ссылки по теме
Подробнее

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

Итак, наконец-то мы решили начать писать спецификации. Поскольку сам процесс для нас новый, пускай хотя бы инструменты будут привычными.

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

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

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

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

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

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

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

Итоги:

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

Пишем спецификации. Прелюдия

Пришла мысль написать несколько заметок (две или три) о том, как мы у нас в конторе пишем спецификации.

На эту тему уже много всего написано, причем не в пример более авторитетными товарищами. Собственно, у них мы и черпали наше вдохновение. Потому и уклон этих опусов будет другой. Не «почему спецификации - это так важно» и «как писать замечательные спецификации», а «как начать писать спецификации на примере отдельно взятой фирмы».

Сначала была ещё мысль рассказать о тех грустных временах, когда мы даже и не задумывались о спецификациях. Но наверное, это не очень интересно. Интереснее, мне кажется, другое. Я опишу, с чего мы начали и к чему пришли сегодня, останавливаясь на каких-то интересных деталях.

Пишем спецификации. Инструменты. Часть 1.
Пишем спецификации. Часть 2. Инструменты. Вики – всё под рукой.

Подробнее

Как мы проводим собеседования

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

Основное правило, которое мы поняли, а потом и прочитали в одной хорошей книжке («Джоэл о программировании»), гласит: приглашая фокусника нужно просить его показать свои фокусы. У нас аналитики пишут ТЗ и описание вариантов использования, программисты строят структуру классов и реализуют многопоточное приложение, ведущие разработчики – архитектуру, а тестировщики – тестируют.
Кстати, эту практику для тестировщиков мы ввели только в прошлом году, это наша гордость. Наш руководитель отдела тестирования, Рита Сафарова, попросила написать приложение, содержащее 10 ошибок. Мы поручили разработку одному новому программисту и теперь даем его соискателям домой, а они присылают тест-кейсы и списки найденных ошибок. Что интересно, когда наше приложение стали тестить, то ошибок в нем нашли в полтора раза больше, чем мы специально посадили. Вот прямо не знаем, что и думать. Наверное, место такое проклятое.
Но вернемся к нашим баранам. Задание мы даем в самом конце собеседования или отправляем по почте уже после собеседования. А сначала мы разговариваем. Разговариваем о навыках человека, о его проектах, в том числе просим рассказать про самый большой из них. Любим спрашивать про книжки, которые человек читает (имеется в виду не труды Дарьи Донцовой, а другое). Очень радуемся, когда человек, например, прочитал “Совершенный код” (мы не все дочитали эту книжку до конца). И спрашиваем, что больше всего понравилось.
Кстати, сейчас мы не устраиваем череду собеседований, а собираемся сразу все вместе. В итоге в собеседовании участвуют 4-5 человек. Некоторых соискателей такое количество людей смущает.
После того, как человек рассказывает о себе и отвечает на наши всевозможные вопросы, мы устраиваем небольшой тест. Берется какая-нибудь логическая задачка, не имеющая отношения к программированию, тестированию или чему-либо полезному. И мы смотрим, как человек ее решает. При этом решение не так важно, как сам процесс решения.
Например, мы просим (я пообещал моим коллегам, никогда больше не задавать ее) решить следующую задачку.

Пусть у вас есть 8 биллиардных шаров, один из которых чуть тяжелее всех остальных. А остальные одинаковые. У вас также есть весы с двумя чашками, как на рынке, но без гирек. Какое минимальное количество взвешиваний вам нужно для того, чтобы найти самый тяжелый шар.
Если человек дает ответ больше трех, нам становится грустно. Если три - то мы начинаем его подталкивать к правильному ответу. И очень немногие сразу отвечают про два взвешивания. Кстати, мы приняли несколько человек, кто не ответил. Тем не менее, это важное задание.

Однажды мы получили ответ “несколько тысяч”. Оказалось, что товарищ услышал про “восемь миллиардов шаров”. C тех пор я стал говорить “восемь шаров для игры в бильярд”.
Неожиданно для себя я недавно нашел эту задачу в книжке Уильяма Паундстоуна “Как сдвинуть гору Фудзи”. А также множество других задач. Мне самому сложнее всего далась загадка про гномов. Мало того, что я ее не отгадал, так еще три раза прочитал ответ, прежде чем понял. Очаровательна книжка, всем рекомендую.
Продолжаем разговор. После расспросов и задачек мы спрашиваем, что человеку интересно узнать про нас. И отвечаем на все вопросы. Иногда нам говорят, что про нас всё прочитали на сайте. На всякий случай я всегда интересуюсь, что же про нас прочитали. Иногда оказывается, что прочитали про системы промышленной автоматизации, контроллеры и SCADA-системы. Это самый грустный момент собеседования. Это значит, что человек пришел к нам совершенно случайно. К счастью это бывает редко, и большинство переступающих наш порог знает, что мы делаем софт.
После ответов на вопросы мы выдаем задание и неделю времени. Это притом, что сделать его можно намного быстрее. Что мы смотрим, получая результаты? Скажу на примере задания для разработчиков. Нас интересует структура классов, оформление кода, правильные переменные и методы. Если мы видим таймер, то мы очень огорчаемся. А оператор goto повергает нас в ступор. К счастью, мы его никогда не видели.
Дальше - мы получаем задание, встречаем нового программиста, знакомим его с будущими коллегами, сажаем на последнее свободное место. Облегченно вздыхаем и тут неожиданно понимаем, что нам крайне необходим еще один внедренец. Но это уже другая история.
Подробнее

Мы в Вики

В Википедии появилась статья о нашем ПК Заявке/АСУРЭО 

Подробнее