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

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

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

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

      Ссылки по теме
    • +17
    • 4,7k
    • 9
    Поделиться публикацией
    Комментарии 9
      +1
      Спасибо за подборку. UML и вправду всегда головная боль а Visio отнимает много времени на красоту и борьбу.

      Хотелось бы узнать как обстоят дела со связями требований с покрытием тестами ( приемочными да и regression тоже ).

      По поводу GeSHi — хороший, но к сожалению правильный разбор пока в глубокой альфе. Требует напильника в каждом конкретном случае.
        0
        Про покрытие тестами мы пока только мечтаем. В этом плане есть некая… безсистемность.
        Относительно связей — в тесткейсах (мы используем Testopia) есть специальное поле для ссылки на документ. В частности — на спецификацию. Обратных связей (спец -> тест) нет.
        А как вы это делаете? Может, посоветуете где почитать?
          0
          А использовать google docs для совместной работы не пробовали?
          На сколько знаю, хранится и история документов, и вставка из офиса прекрасно работает. Совместная работа реализована на «ура» (во всяком случае с таблицами, документы я совместно не редактировал).
          Правда надо иметь постоянный выход в интернет.
          Но и как плюс заказчик всегда может посмотреть и исправить что-либо.

          Не знаю как там с диаграммами разными: не пользовался.
          Да и думаю, «свое» Вы уже нашли.
            0
            google docs не подходит для работы программерской конторы. Там упор на оформление, а не содержание делается.
            0
            Первая часть находится элементарно, но всё же стоит явно указать прямую ссылку на начало.
              0
              Wiki мы тоже используем активно, правда другой движок — Moin.
              Но используем для обзорных статей в основном, HowTo hotlinks, некоторой метаинформации о проекте и прочее.
              Крупные, сложные, структурированные документы — например, SRS/SDS документы все же пишем в Ворде.
                0
                Рад видеть людей со схожими взглядами.

                Пару наших соображений.

                * В свое время (еще до WikEd-а) тоже прикручивал FCKEditor к MediaWiki, но потом понял, что это концептуально неверно — должен быть режим автора в WYSIWYM-парадигме, а предпросмотр результата нужен не так часто, и отдельно — т.е. вариант LaTeX-верстки, когда автор работает с текстовой разметкой, а результат регулярно просматривает отдельно в DVI-вьевером — правильный. И мы сделали специальный режим просмотра с регулярным автообновлением — отдельное окно можно просматривать на втором мониторе.

                * PDFBook/Экспорт в Word — мы столкнулись, что задача не только в том, чтобы как-то вытащить контент в Word, но и реализовать всякие фишки бумажной верстки — автонумерация и целостные «бумажные» ссылки (с номерами разделов и страниц), и т.п. Мы реализовали это на HTML-представлении спецполей MSWord… Тут в общем, было бы интересно посмотреть на код — вы планируете публиковать ваши доработки?

                * PlantUML — интересно. В свое время, когда я делал «подход к теме», его еще не было, MetaUML (как основанный на динозавре METAPOSTе) был отвергнут, реализован UMLGraph, но он у нас не шибко идет — реализация через Java-компиляцию с рефлексией — идиотизм, пугает людей невнятными ошибками и вообще, завязка на Java-синтаксис, с выносом всего что не ложиться туда в комментарии — тупик. Я собирался делать свой UML-язык (с блекджеком и шлюхами), видимо, на основе YAML, но слава богу не стал — похоже появилось что-то стандартное (ненавижу изобретать колесо). Просмотрел синтаксис — немного funky, так что интересует ваше мнение — реально ли PlantUML удобен? Вменяемо ли ругается при ошибках в синтаксисе? Какие основные у него минусы?

                P.S. Просьба заменить PDF-ссылку (там дурацкая двухколоночная верстка по требованиям организаторов на Web-версию).
                  0
                  Ссылку поправил.

                  * PDFBook/Экспорт в Word — мы пока про такие «фишки» не задумывались. Сейчас у нас выгрузка в ворд решает только одну задачу — отослать заказчику спецификации, получить от него реакцию в виде комментариев в тексте.
                  Про публикацию наших разработок — вот пока не спросили, не задумывались. В принципе не жалко. Сегодня еще раз посмотрел на «доработанный» нами PDFBook. Оказалось, общих вещей (для PDF и DOC) там очень мало, так что имеет смысл вынести наш экспорт в ворд вообще в отдельный плагин, а PDFBook оставить оригинальный. В ближайшие дни это сделаем, и куда-нибудь выложу. Думаю, польза будет всем :)

                  * PlantUML — насчет удобств могу рассуждать только в сравнении с Визио. Других вариантов «текстового» описания UML не пробовал.
                  Удобства:
                  1) простой, понятный язык. Даже наглядный — всякие стрелочки, кружочки.
                  Поэтому легко запоминается синтаксис.
                  2) без формализма (фанатизма). Не надо как-то специально описывать сущности. Они создаются при появлении в тексте.
                  Например: Child --|> Parent
                  сразу нарисует два прямоугольника-класса со стрелкой-наследованием.
                  Неудобства:
                  1) прожорливость реализации. PlantUML — это ява-приложение, которое на выходе дает опять-таки текстовое описание графа, которое подается на вход Graphviz. И вся эта цепочка запускается соответственно из PHP. Поэтому страница с 4 и более диаграммами сохраняется сильно долго.
                  2) непредсказуемость размещения блоков диаграммы. Нет никакой возможности «подсказать», что этот класс я хочу видеть наверху, а эти три — под ним. Часто по смыслу хочется расположить их иначе, чем предлагается программой.
                  Сообщения об ошибках — конечно не верх информативности, но максимум раза с третьего :) найти причину можно. Просто пишется строка, где по мнению программы есть ошибка. Без подробностей.

                  > мы сделали специальный режим просмотра с регулярным автообновлением
                  Можно ли об этом поподробнее? Как это реализовано? Как выглядит?
                    0
                    >Можно ли об этом поподробнее? Как это реализовано? Как выглядит?
                    Ну зайдите на wikisandbox.custis.ru/ попробуйте редактировать какую-нибудь статью и включите галку Автопредпросмотр — тогда она будет показывать в отдельном окне-вкладке (можно утащить ее на второй монитор), предпросмотр, соответствующий вашему текущему, еще не сохраненному, тексту.

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

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