Non-WYSIWYG диаграммы в вики

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



    Я хочу поговорить о том, как вставлять диаграммы на страницы вики (под словом вики в этой статье подразумевается исключительно MediaWiki). Стандартный подход — хранить диаграммы в файлах внутри самой вики — имеет свои недостатки; о них — под катом. Я попробовал использовать Graphviz — инструмент, который сам рисует графы по заданным данным. Вот исходник картинки, с которой началась эта статья:

    digraph A {
    Feedback -> New_Assigned [dir="both"];
    New_Assigned [label="New / Assigned"];
    New_Assigned -> Rejected [dir="both"];
    Reopen -> Rejected;
    Reopen -> New_Assigned;
    New_Assigned -> Resolved -> Testing -> Approved -> Closed;
    Testing -> Closed;

    { rank=same; Feedback; Reopen; }
    { rank=same; Resolved; Testing; Approved; }
    }

    Проблема кросс-платформенности и «где хранить исходник»


    Программист Вася нарисовал в любимом Omnigraffle диаграмму, сохранил её в png и загрузил в вики. Неделю спустя к архитектуре проекта добавился новый компонент, и PM Катя захотела отредактировать диаграмму. Но сделать это сразу она не может, потому что а) Вася заболел, а исходник лежит только на его машине; б) Катя пользуется Windows, где омниграффл как-то не работает.

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

    Посмотрим на менее естественное non-WYSIWYG решение.

    Graphviz в вики


    Диаграммы в графвизе описываются текстом — так, как в примере, данном в начале статьи. Сильные стороны графвиза:
    — достаточно простой синтаксис;
    — он сам продумывает, как расположить элементы диаграммы наиболее оптимально — например, минимизирует количество пересечений стрелок (aka рёбер графа);
    — диаграмму всегда легко отредактировать, и лэйаут автоматически адаптируется под новые данные;
    — кросс-платформенность, конечно — бинарники графвиза распространяются для винды, макоси и многих линуксовых сборок.

    Экстеншн для вики добавляет тег <graphviz>, внутри которого можно писать код диаграммы. Установка экстеншна занимает несколько минут: надо скачать архив (ссылки даны ниже), распаковать в папку extensions, и дописать в LocalSettings.php строку, подключающую плагин. Чтобы диаграммы рендерились, на сервере, на котором крутится вики, должен стоять графвиз.

    Результат


    Что получаем ценой небольших усилий:
    — можно рисовать и редактировать диаграммы, не ставя дополнительный софт;
    — у каждой диаграммы есть прозрачный исходник;
    — диаграммы можно «рисовать» хоть на айфоне.

    Минусы


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

    Killer Feature


    Я не хотел подробно перечислять в этой статье фичи графвиза, но очень хочу упомянуть об одной особенности. Любой узел диаграммы, нарисованной графвизом, можно превращать в ссылку! Это невероятно удобно, если диаграмма описывает взаимодействие компонентов какого-то сложного приложения, так как обеспечивается связность между диаграммой и информацией о компонентах. Например, нажимая на квадрат, в котором написано «Storage», читатель сразу же попадёт на страницу, описывающую хранилище данных.

    Ссылки



    Спасибо за внимание! В комментариях предлагаю делиться своим опытом использовани графвиза и кидать ссылки на ценные источники информации по теме.
    Ads
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More

    Comments 15

      +2
      Еще напомню про www.websequencediagrams.com/ ;)
        0
        Отлично! :)
        +3
        > (под словом вики в этой статье подразумевается исключительно MediaWiki)

        Например, для DokuWiki тоже есть соответствующие плагины для построения диаграмм: ditaa, diagram (http://nikita.melnichenko.name/projects/dokuwiki-diagram/) и др.
        +4
        Мы много лет используем Graphviz и другие типы семантических графов в наших MediaWik-ах (а также в автогенеримой документации и т.п.).
        lib.custis.ru/Graphviz

        Все наши расширения и доработки опубликованы в open-source
        wiki.4intra.net/Mediawiki4Intranet
          0
          Хочу поделиться еще одним интересным использованием GraphViz. Проект canviz занимается отрисовкой этих графов прямо на Canvas из Javascript. Соответственно, с ним GraphViz можно использовать где угодно, где есть возможность вставлять свой Javascript.
            +2
              0
              Спасибо, отличный сервис.
              0
              Я рисую диаграммы в программе Dia, она кроссплатформенная. Картинку в вики вставляю в формате png, а рядом прикрепляю исходник.
                0
                Кстати, у нас сделан экстешн, и MediaWiki автоматически растеризует Dia-диаграммы.
                0
                Плюсую вам всем карму и забираю в закладки статью. Когда-то при изучение алгоритмов сжатия, увлекся хаффманом. Дерево тоже строил, но визуально оно сложно воспринималось. Будет время, исполню свою маленькую мечту.
                  0
                  Ещё есть PlantUML, Java-приложение, требующее Graphviz для работы. Всякие диаграммы классов с ним создавать проще, чем с GraphViz. Умеет интегрироваться с MediaWiki, trac, Redmine и кучей всего, включая MS Word и OpenOffice.org / LibreOffice Writer
                    0
                    Отличная штука, я пользовался ею для рисования диаграммы зависимости тикетов в trac. Для него тоже есть плагин с graphviz.
                      +1
                      А я пользуюсь my.origramy, когда надо быстро набросать схемку в онлайне, для wiki изображения тоже умеет генерировать.
                        0
                        Есть ещё монстрик gephi.org/

                        Only users with full accounts can post comments. Log in, please.