Wiki движки для публикации пользовательской документации

Вкратце тезисы были такие:

• Наиболее удобная форма пользовательской документации – онлайн документация;
• Такую документацию удобно распространять, контролировать доступ, поддерживать и развивать, получать обратную связь от пользователей;
• Существует множество возможностей и инструментов для размещения документации в Интернет, и каждый может выбрать по своему вкусу и возможностям;
• Наиболее традиционный инструмент – wiki платформы (wiki-движки), о них я и хочу рассказать в этой статье.

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

Изучив wiki-движки подробнее, представляю Вашему вниманию краткий обзор DokuWiki – простой и мощный движок, который был разработан специально для онлайн документации.

DokuWiki – свободный программный продукт, распространяемый по лицензии GPLv2, работает на любой платформе, на которой Вам удастся завести PHP. Отличительной особенностью этого движка является то, что кроме PHP для работы ему ничего не нужно, ни MySQL ни PostgreSQL, т.е. будет работать практически на любом самом дешевом виртуальном хостинге.

Устанавливается DokuWiki предельно просто. Идем на страницу загрузки http://download.dokuwiki.org/, выбираем Version – Stable, Languages – выбираем нужные языки, Popular Plugins – рекомендую сразу добавить Upgrade Plugin и Video Share Plugin (плагины можно добавить/удалить потом). Нажимаем кнопку Download, получаем ZIP архив с движком.

Дальнейшее сильно зависит от того где и как Вы собираетесь размещать сайт с документацией. Я попробовал это сделать в поддомене своего сайта на виртуальном хостинге, это очень просто. В панели управления хостингом создаем web-домен, не забываем указать, что нужна поддержка PHP. Хостинг создает пустой каталог для нового сайта, закидываем через панель туда ZIP-файл с движком и даем команду распаковать. Вот и вся установка, переходим к настройке.

Открываем страницу начальной настройки:

http://<путь к установленному DokuWiki>/install.php

Первым делом переключимся на понятный язык, справа вверху есть список выбора Choose your language и нажимаем кнопку Update.

Слева указываются основные параметры установленного движка DokuWiki:

1. Суперпользователь – это логин самого главного администратора, который может ВСЕ;
2. Полное имя – это имя суперпользователя будет отображаться;
3. Эл. адрес – на этот адрес в случае необходимости будут отправляться системные уведомления, в т.ч. инструкции по сбросу и установке нового пароля;
4. Пароль и повторите – пароль суперпользователя, используйте безопасные пароли;
5. Исходная политика прав доступа – здесь для начала рекомендую выбрать «Общедоступная вики», эти настройки при необходимости можно будет изменить в процессе эксплуатации;
6. Разрешить пользователям самостоятельно регистрироваться – не разрешайте;
7. Пожалуйста, выберите тип лицензии для своей вики – с лицензиями у нас все сложно, выбирайте «Не отображать информацию о лицензии»

Нажимаем сохранить, удаляем файл install.php из каталога хостинга. Обязательно ознакомьтесь с рекомендациями по безопасности от разработчиков и выполняйте их.

Первоначальная настройка завершена. Теперь мы готовы начать творческий процесс, однако, если у Вас нет опыта написания wiki, следует прояснить для себя ряд ключевых моментов.

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

Если проводить аналогию с документацией к типовым конфигурациям 1С:Предприятие, то статья wiki будет соответствовать содержимому заголовков второго и третьего уровня. Wiki-статьи, соответствующе второму уровню заголовков печатной документации будут описывать «карты» бизнес-процессов, давать пользователю общий взгляд на процессы и содержать ссылки на wiki статьи, соответствующие третьему уровню заголовков, т.е. на детальное описание подпроцессов.

Статья пишется на специальном markdown языке wiki-разметки. Одна из основных идей wiki-движков состоит в том, что все необходимые для наполнения wiki инструменты содержаться в самом wiki-сайте. DokuWiki эту идею поддерживает и в него встроен простой визуальный редактор статей. При желании Вы можете установить плагин с более мощным WYSIWYG редактором, если планируется написание текстов в Word с последующей вставкой в DokuWiki, то Вам потребуется редактор с такой функцией, например, CKGEdit Plugin. Однако после года использования DokuWiki я рекмендую все-таки привыкать писать в markdown разметке, так у Вас будут получаться красивые статьи в стилистике Wiki.

Используйте в тексте цветные стикеры, выводя в них главные мысли и важные моменты — это хороший стиль в Wiki. Стикер вставляется тегом <note>.

Внутри статьи все похоже на обычную структуру обычного документа, который Вы создаете в Word’е. Используйте заголовок 1-го уровня H1 для того, чтобы дать название статье, Н2, Н3 и далее для того, чтобы создать структуру статьи. Когда в статье более 3-х заголовков DokuWiki автоматически создаст к ней оглавление.

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

Ссылки – очень важный инструмент wiki. Настолько важный, что для того, чтобы создать новую статью Вам придется сначала создать на нее ссылку и перейти по ней. DokuWiki сообщит Вам, что статья еще не создана и предложит сделать это. Дело в том, что в идеологии wiki не приветствуются статьи, на которые никто нигде не ссылается, есть подозрение, что такие статьи никому не нужны и потому не стоит их писать. Подробнее о ссылках почитайте в документации разработчика.

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

Среднестатистическая документация к конфигурации 1С:Предприятие состоит из текста, маркированных и нумерованных списков, таблиц, скриншотов и схем. В онлайн-версии этот набор можно дополнить гиперссылками и видеороликами. Все это без проблем поддерживается DokuWiki. Если что-то не поддерживается, всегда есть возможность вставить HTML и PHP код внутрь статьи. Мне, например, очень нравятся схемы, создаваемые в облачном редакторе Draw.io, для их вставки нужно использовать HTLM код.

Наполнять wiki документацией, разумеется, лучше в закрытом доступе, либо развернуть все в локальной сети, либо ограничить доступ. В DokuWiki простая и мощная система управления доступом. Создайте две группы доступа: @editors – в нее добавляйте сотрудников, работающих с документацией, установите разрешения на создание и загрузку файлов и @users (она создана по умолчанию) – в нее добавляйте пользователей, установите разрешение на чтение, или откройте доступ на чтение для всех @ALL.

Для быстрого превращения онлайн статьи в PDF файл есть специальный плагин DW2PDF. Работает просто, к URL статьи в адресной строке добавляется параметр ?do=export_pdf и получаем красивый PDF файл с QR кодом ссылки на онлай статью, вот так.

А если в PDF нужно сконвертировать целую книгу, то для этой цели есть другой полезный плагин BookCreator. После его установки нужно сделать специальную статью-страницу, где будет производится сборка книги. Указываете на ней один единственный тег ~~BOOK~~ и пользуетесь.

Подведем итог. DokuWiki – простой и достаточно мощный движок для создания онлайн документации к конфигурациям на платформе 1С:Предприятие.

К достоинствам можно отнести:

• Простота установки, настройки и администрирования;
• Русская локализация интерфейсов;
• Гибкая система управления доступом;
• Большой выбор расширений и шаблонов;
• Адаптивный интерфейс для ПК, планшетов и телефонов.

Из недостатков следует отметить:

• Отсутствие встроенной системы рейтингования статей и обратной связи;
• Отсутствие встроенной системы веб-аналитики (можно подключить сторонний плагин Google Analytics);
• Отсутствие системы авторизации пользователей через социальные сети (подходящего плагина не нашлось).

Ссылки:

• Запись вебинара "Пользовательская документация для конфигураций 1С:Предприятие" infostart.ru/webinars/529307
• Сайт проекта DokuWiki dokuwiki.org
• Песочница PlayGround
• Документация от разработчиков dokuwiki.org/manual
• Моя база знаний на движке DokuWiki: http://wiki.lineris.ru/