Любой компании, специализирующейся на разработке программного обеспечения, приходится решать две важные задачи: одна состоит в организации эффективного документирования и взаимодействия с клиентами, другая – в построении внутренней информационной базы знаний. Традиционно технической документацией в компании занимается небольшая группа экспертов, владеющих технологиями верстки, публикации и групповой работы, но с ростом популярности «скорых» (agile) практик становится критически важным привлекать к работам по постановке задач или рецензированию документации максимально широкий круг специалистов как из числа сотрудников компании, так и из представителей заказчика. Качество верстки, полиграфии и литературного стиля уже не так важны, как актуальность, полнота учета интересов всех заинтересованных сторон и верификация широким кругом специалистов. Существенно, чтобы используемая технология поддерживала совместную работу, причем для различных групп участников важными являются разные и местами несовместимые между собой аспекты. Например, для команды производителей документации, обозначенной на рис. 1 как «ИТ-команда», ключевым является фактор эффективности, выражающийся в обеспечении параллельной работы с минимумом блокировок и узких мест, например, правильной считается практика обязательного использования систем контроля версий с неблокирующей моделью «Копирование – Изменение – Слияние».

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

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

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

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

Ожидаемое решение

Для эффективной совместной работы нужно радикально избавляться от артефактов в бинарных форматах – только для «плоского» текста, разбитого на строки ограниченной длины, существуют хорошо зарекомендовавшие себя универсальные алгоритмы вычисления различий и автоматического слияния различных версий. Но, выбрав текстовый формат документа, какой же язык разметки выбрать? Рассмотрим классификацию разметок (рис. 2).

Разметки, основанные на препроцессоре (TeX, LaTeX) и на жестких SGML-спецификациях (HTML, DocBook), непросто использовать – управляющие элементы разметки, будь то тэги или макросы, занимают много места, а разметка документа ориентируется не на удобство автора, а на обработку препроцессором или стандартизированным компилятором. В результате надо быть готовым к трудноуловимым и даже необъяснимым ошибкам при работе с TeX или держать в голове иерархию вложенности сотен тэгов при использовании структурной SGML/XML-разметки (DocBook, XHTML). Конечно, сильная команда сможет вполне успешно порождать документацию на любом языке разметки, но тогда не будет простоты, а необходимость развертывания системы сборки на каждом рабочем месте отрицательно сказывается на доступности.

Уже в 70-е и 80-е годы, когда зародились поколения разметок SGML и TeX, появились и так называемые «плоские» (plain text) разметки, основной смысл которых заключался в форматировании документа с помощью пустых строк, отступов и десятка символов пунктуации так, что текст оставался вполне читаемым и без обработки. Такая разметка не вызывает трудностей даже у начинающих пользователей и при этом вполне достаточна для ведения базы знаний или технической документации.

Что еще пожелать от «серебряной пули»? Доступности – просмотр гипертекста в любимом браузере, правка и редактирование там же. Ходить по гиперссылкам умеет и ребенок, но надо сделать так, чтобы и ссылаться можно было легко и понятно. Чтобы было управление версиями и обеспечивалось удобство: составные документы, шаблоны. В идеале должна быть также возможность подключения и использования любых предметно-ориентированных языков (Domain Specific Language), например построение графов и даже UML-диаграмм по краткому текстовому описанию, математических формул в общепринятой разметке TeX/LaTeX, автоматическое форматирование и синтаксическая раскраска для фрагментов кода и т.п. Ну и конечно, требуются средства поиска и навигации – категории и полнотекстовый поиск.

Wiki

В 2001 году на wiki-системе стартовала Wikipedia, а в 2007-м слово wiki* получило официальную прописку в Оксфордском словаре. Теперь практически все базы знаний сообществ сделаны на wiki-системах, где они вытесняют «классические» системы документооборота, в них же ведут техническую документацию к программным продуктам. Почему это происходит? Потому, что перечисленные ожидания от «серебряной пули» прекрасно покрываются средствами wiki: простой язык разметки; совместное редактирование; правка и публикация по месту, когда из чтения можно немедленно перейти к редактированию, не разыскивая исходные тексты документа; централизованное хранение и версионность; упрощенное построение ссылок.

При работе с файлами в стандартных языках разметки (TeX, LaTeX, SGML Docbook, HTML) нужно держать в голове нетривиальные соответствия между идентификаторами и названиями структурных блоков (секций, глав, разделов) и плюс еще помнить, в каком файле что лежит. Это способствует целостности, но очень затрудняет внесение новой ссылки. Не говоря уже о том, что для грамотной работы с файлами обязательно нужна система контроля версий, и все это минусы к «простоте и доступности». В wiki реализовано централизованное хранение всех текстов: идентификатор, название и заголовок для каждого текста – это одно и то же. Еще одна дружелюбная к пользователю денормализация – перенаправления ссылок и опережающие ссылки на несуществующие статьи.

Отлично подходят для документирования и управления знаниями внутри компаний и социальные свойства wiki:

  • никто не знает всего, но можно собрать знания «с миру по нитке»;
  • легче поддерживать актуальность – процесс исправления ошибки очень прост, и можно не бояться все испортить – есть контроль версий;
  • совместное редактирование влечет за собой совместную ответственность, вырабатывает культуру обсуждений и поиска правильного решения;
  • легкость совместного редактирования ведет к многократным итерациям и улучшает качество (эффект «взбивания сливок»);
  • легкость порождения статей способствует фиксации больших объемов знаний.

Более того, многие проблемы, характерные для общедоступных wiki-систем, внутри компании перестают быть таковыми: спам и вандализм – поможет служба кадров; толпа невежд лоббирует ерунду – обнаружена серьезная проблема в компании, требуется социальное решение; неразрешимые флеймы – немедленное проведение устных переговоров до достижения компромисса; расстраивает потеря авторства – похоже, кто-то не любит работать в команде.

Конечно, надо помнить и о технических проблемах, ограничивающих область применимости wiki. Если нужна книга с высококачественной версткой или полиграфией, то лучше использовать LaTeX. Если заказчик требует сдавать документацию по ГОСТу, с проверкой форматирования службой нормоконтроля, то разумно использовать SGML DocBook. Но вообще тенденция такова, что ценность бумажной технической документации уже почти упала до нуля. Правда, есть еще области электронных документов, в которых требуется качественная верстка по «листу/экрану», – это презентации. Здесь можно порекомендовать LaTeX/beamer с использованием автогенерации текста, диаграмм, картинок под управлением системы сборки типа SCons. Но в целом wiki если и не тянет на «серебряную» пулю, то «посеребренной» называться вполне может. И самое главное, кроме словесных аргументов есть убедительная проверка этого подхода практикой. Почти все знают Википедию, но не все знают, что ее прародителем был проект Nupedia, основанный на иных подходах, и за четыре года его работы было сделано лишь 23 завершенные статьи. С переходом проекта на первый wiki-движок, начался настоящий бум: 2004 год – 300 тыс. статей; 2005 – 500 тыс. и 2007 – 2 млн статей.

Проблемы выбора

Wiki-систем уже больше сотни, и у каждой свой собственный язык разметки и интерфейс. Выбрать непросто, и дискуссии по выбору оптимальной wiki-системы ведутся очень жаркие – сравнивается функционал, эстетика и архитектура. Ошибка в выборе может надолго, если не навсегда, отпугнуть компанию от использования wiki-систем: «Вики? Даже не предлагайте! Мы тут пробовали: кошмар, убогая, неудобная, ничего найти нельзя, никто ее не знает, сломалась, и мы все потеряли». Чтобы этого не случилось, мы предлагаем в первую очередь ориентироваться на комплексную характеристику функционала системы — популярность и распространенность.

У каждой из популярных и распространенных wiki-систем есть как положительные, так и отрицательные особенности. Например, Confluence очень хорошо интегрируется с известным баг-трекером Jira, но является платной. TWiki бесплатна и поддерживает управление правами на статьи, но написана на Perl. Система MoinMoin понравится любителям Python, а JotSpot уже понравился Google и его превратили в Google Sites. У MediaWiki объем размещенного контента, количество пользователей и разработчиков на порядки больше, чем у любой другой wiki-системы. Разметка MediaWiki дает возможность копировать или публиковать материалы в Википедии, а ее открытая архитектура имеет сотни точек расширения (Hooks, Extensions), куда можно подключать свои модули, реализуя собственные предметно-ориентированные языки, дополнительные интерфейсы редактирования и публикации, поиска и навигации. Имеются тысячи готовых расширений, которые устанавливаются простым копированием в каталог /extensions, – именно система расширений превращает MediaWiki в многофункциональный «швейцарский нож». Вот несколько «штопоров», «напильников» и «пассатижей» из «ножа» MediaWiki:

  • автоматическое построение графов – создание направленных и неориентированных графов по краткому текстовому описанию, например графов информационных и материальных потоков, диаграмм состояний или иерархий счетов, схем проводок или каких-либо классификаций;
  • автоматическое построение некоторых типов UML-диаграмм, сформулированных на специальном текстовом языке UMLGraph, рекомендованном Мартином Фаулером, известнейшим популяризатором UML;
  • построение графиков по тексту – создание двух- и трехмерных графиков и диаграмм по записанным формулам или наборам данных, например, иногда требуется очень быстро публиковать или обновлять Scrum Burndown Chart;
  • LaTeX – вставка формул и целых LaTeX-фрагментов,
  • Mindmaps – публикация интеллектуальных карт;
  • MediaWikiQuizzer – система тестов, превращающих wiki-систему в систему дистанционного обучения;
  • полнотекстовый поиск – используется отличный поисковик Sphinx, поддерживающий русскую морфологию.

Особенности внедрения

Для внедрения и поддержания wiki полезно, чтобы в компании был один или несколько энтузиастов, получающих удовольствие от «борьбы за качество», – поищите их среди технических писателей или тестировщиков. Wiki – это не помойка, требующая регулярной уборки, это скорее сад, где регулярные усилия садовника придают растениям правильную форму.

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

Встречаются жалобы, что если не следить за wiki-системой, то за год-другой она превращается в информационную свалку, в которой ничего нельзя найти. Здесь рекомендуется обязательно сделать полнотекстовый поиск с русской морфологией, причем если встроенный поиск в wiki плохой, то самое простое решение – установить бесплатный OmniFind Yahoo! Edition. Чуть сложнее подключить поисковую библиотеку Sphinx. Не надо забывать и о встроенных функциях wiki-систем по борьбе с нецелостностью и неактуальностью: поиск двойных перенаправлений, битых ссылок и т.п. Здесь можно порекомендовать LinkChecker.

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

Что делать, если, несмотря на все попытки и усилия, wiki-системы не приживаются? Значит, они вам и не нужны, а если все-таки есть нерешенные проблемы в управлении знаниями или гибком документировании при взаимодействии с заказчиком, то дело явно в другом: в людях, в задачах компании и ее приоритетах. Возможно, тогда никакой другой волшебный инструмент не сможет вам помочь.

При всем богатстве выбора не идеальное, а местами и «косое» решение стало востребованным, ибо остальные, при всех возможных преимуществах, проигрывают wiki.

Стас Фомин (stas@custis.ru) – заместитель директора по информационным технологиям компании «Заказные ИнформСистемы» (Москва).


Рис. 1. Аспекты документирования и взаимодействия с заказчиком

Рис. 2. Языки разметки текстовых документов


*Технологию wiki предложил Уорд Каннингем – американский программист, один из пионеров применения паттернов и экстремального программирования. В конце 1980-х он начал разрабатывать концепцию wiki, впервые реализовав ее на практике в середине 1990-х.


Гипертекст – от Memex до wiki

Прошло немного времени с момента изобретения электронной почты, Internet-конференций, форумов и чатов, а их уже стали называть коммуникационными средствами первого поколения –
появилось второе, к которому относят технологии blog, wiki и RSS feeds. Для корпоративных применений наибольший интерес представляет wiki – технология, позволяющая простыми и дешевыми средствами перейти к использованию гипертекстов.

 

Поделитесь материалом с коллегами и друзьями