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

13.09.17

Архитектура

В июне 2016 года я провел вебинар по созданию пользовательской документации для конфигураций, разрабатываемых на платформе 1С:Предприятие. Одна из тем, вызвавших интерес: онлайн документация.

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

  • Наиболее удобная форма пользовательской документации – онлайн документация;
  • Такую документацию удобно распространять, контролировать доступ, поддерживать и развивать, получать обратную связь от пользователей;
  • Существует множество возможностей и инструментов для размещения документации в Интернет, и каждый может выбрать по своему вкусу и возможностям;
  • Наиболее традиционный инструмент – 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);
  • Отсутствие системы авторизации пользователей через социальные сети (подходящего плагина не нашлось).

Ссылки:

 

документация разработка wiki

См. также.

Кейсы автоматизации Платформа 1С v8.3 Энергетика и ЖКХ Россия Бесплатно (free)

Делимся опытом автоматизации учета башни раздачи воды.

27.12.2023    1700    0    slavik27    4    

15

Отчеты и дашборды Бизнес-аналитик Бухгалтер Пользователь Платформа 1С v8.3 Бухгалтерский учет 1С:Бухгалтерия 3.0 Бухгалтерский учет Бесплатно (free)

Если вы привыкли выгружать бухгалтерские операции в Excel и дополнять их там управленческой информацией, вы сможете значительно сэкономить время, получая нужные управленческие отчеты в бухгалтерской программе сразу, без лишних движений. Представляем решение для самостоятельного внедрения управленческого учета в 1С:Бухгалтерии.

11.12.2023    1924    0    Serg_Tangatarov    2    

15

Архитектура решений Программист Бесплатно (free)

Рассмотрим применение архитектурной проверки задач в процессе разработки.

30.10.2023    4454    0    ivanov660    10    

31

Кейсы автоматизации Работа с требованиями Анализ бизнес-процессов Бесплатно (free)

Автоматизировать производственные процессы в 1С:ERP без доработки типовых механизмов очень сложно. А дорабатывать типовые механизмы 1С:ERP не всегда оправданно. Решением может стать технология разработки Рабочих мест, которая позволяет автоматизировать самые сложные участки последовательно – шаг за шагом, процесс за процессом. Расскажем о том, как помочь пользователям вводить большое количество данных, не нарушая порядок ввода и полноту заполнения всех необходимых реквизитов, и как вовлечь сотрудников Заказчика в разработку и тестирование функционала Рабочих мест.

26.10.2023    2246    0    user1754524    15    

17

Кейсы автоматизации Платформа 1С v8.3 1С:ERP Управление предприятием 2 Бесплатно (free)

Когда проект внедрения ERP в крупном холдинге захлебывается в проблемах производительности и в отчаянии пользователей, нужен комплексный подход. Расскажем о битве за производительность и об организационных мероприятиях по наведению порядка в системе и коллективе.

29.08.2023    3143    0    ke_almaty    0    

14

Архитектура Рефакторинг и качество кода Обновление 1С Программист Стажер Платформа 1С v8.3 Бесплатно (free)

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

10.08.2023    10185    0    1c-izhtc    37    

22

Кейсы автоматизации Внедрение изменений Пользователь Платформа 1С v8.3 1С:Управление нашей фирмой 3.0 Управленческий учет Бесплатно (free)

Стабильное качество выпускаемой продукции и ее соответствие нормативным документам (ТУ, ГОСТам, СМК) для активного предприятия является конкурентным преимуществом, так как оно подчеркивает, что на предприятии отлажены контрольные процедуры на входящее сырье, производство полупродуктов и готовой продукции, доставки. В своей практике я принимал участие во внедрении цифровых инструментов в сельском хозяйстве, где показателями зерна служат влажность, засоренность, крупность и т.д.; в металлургии — перед литьем в формы надо проверить сплав на содержания железа, алюминия, магния и т.д.; в кабельной промышленности в дополнение к физическим свойствам типа геометрии, длины, шероховатости, надо выдерживать и электротехнические показатели. 

22.05.2023    1611    0    Ingraf    0    

16
Комментарии
Подписаться на ответы Инфостарт бот Сортировка: Древо развёрнутое
Свернуть все
1. Steelvan 304 13.07.16 10:18 Сейчас в теме
Зачет.

Мы как раз разрабатываем программу ОптимаСофт:Коннект для коллективной работы с документацией.
В качестве функционала планируется:
*) Использовать только встроенный в1С движок работы с документами.
*) Сохранение документов в odt и pdf;
*) Встроенный редактор диаграмм;
*) Публикация через интернет на основе http сервисов в виде дерева со страницами (что-то похожее на http://www.elma-bpm.ru/kb/help/elewise.elma.bpm.web.common/content/help/webhelp/)
Это даст возможность публиковать данные из базы напрямую в интернете.
*) Работа с документами в админке через тонкий клиент.
*) Возможность оставлять на сайте (публикации в интернете) комментарии.
2. kuld 248 13.07.16 22:34 Сейчас в теме
(1) Steelvan, (1) Steelvan, Тема полезная.
Надеюсь, публикация в Интернет не через веб-интерфейс 1С:Предприятия?
3. o.nikolaev 214 20.10.16 10:04 Сейчас в теме
Я Confluence использую, интегрированный с Jira. Нарадоваться не могу. К сожалению на 1С-ине чего-то близкого не нашел :-( Только СППР не надо, пожалуйста, предлагать :-D
Оставьте свое сообщение