Wizard: открытая система управления документацией

Wizard — это открытая система управления документацией, которая в настоящее время поддерживает три типа управления документацией.

• Markdown: основной тип документации Wizard, который используется для обмена информацией в повседневной работе команды разработчиков. В Wizard проект Editor.md был расширен функциями добавления шаблонов документов, преобразования JSON в таблицы, вставки изображений и других функций.
• Swagger: поддерживает стандарт OpenAPI 3.0 и интегрирован с официальным редактором Swagger. Предоставляет функции добавления шаблонов документов, полноэкранного редактирования и автоматической синхронизации документов.
• Table: этот тип документации похож на электронные таблицы Excel и интегрирует проект x-spreadsheet.

В Wizard документы, над которыми ведётся работа, автоматически сохраняются в локальном хранилище Local Storage, чтобы предотвратить потерю данных при случайном закрытии страницы.

Основные функции включают:

• управление документацией типов Swagger, Markdown и Table;
• управление историей изменений документации;
• сравнение различий между версиями документации;
• управление правами пользователей;
• управление группами проектов;
• унифицированная аутентификация LDAP;
• поиск документов и тегов;
• режим чтения;
• комментарии к документам;
• уведомления о сообщениях;
• совместное использование документов;
• статистические функции;
• поддержка диаграмм процессов, последовательных диаграмм, круговых диаграмм и научных формул Tex LaTex;
• переключение между несколькими темами.

Если вы хотите быстро попробовать возможности Wizard, вы можете использовать Docker для создания полного сервиса Wizard.

Чтобы создать сервис Wizard с помощью Docker, перейдите в корневой каталог проекта и выполните команду docker-compose up. Это позволит вам быстро запустить сервис Wizard и получить доступ к нему по адресу http://localhost:8080.

Происхождение

Для поощрения документирования процесса разработки изначально мы выбрали проект ShowDoc в качестве инструмента управления документацией. На тот момент команда была небольшой, и все использовали Markdown для написания простых документов по разработке. Однако по мере роста команды и разделения на фронтенд и бэкенд, использования Markdown стало недостаточно. Тогда мы решили использовать популярный в мире открытого кода инструмент Swagger для создания документации по API. Но для большого количества документации, включая документацию по дизайну, процессам, архитектуре, техническим решениям и изменениям в базе данных, требовалось единое место для хранения и управления. Поэтому я решил разработать инструмент Wizard, объединяющий Markdown и Swagger для управления документацией.

Первоначально идея проекта Wizard была простой — объединить Markdown и Swagger и предоставить простой интерфейс управления. Однако после начала использования в команде стало ясно, что простого управления документацией недостаточно для корпоративного инструмента. Появились требования к функциям, таким как управление правами, история изменений документов, поиск документов, классификация и другие. Эти требования способствовали дальнейшему развитию функциональности Wizard.

Функции, добавленные в Wizard:

• Управление правами пользователей: реализовано на основе модели разрешений Gitlab, где пользователи делятся на администраторов и обычных пользователей. Пользователи могут быть организованы в группы, а права чтения и записи могут быть назначены индивидуально для каждого проекта.
• Группы проектов: в Wizard документация организована по проектам. Со временем количество проектов увеличилось, и появилась необходимость в организации структуры проектов в виде каталогов.
• История изменений документов: Wizard сохраняет снимок каждого изменения документа, предотвращая потерю данных из-за ошибок. Все ключевые операции, такие как изменения, добавления и удаления, записываются в журнал аудита.
• Сравнение различий документов: чтобы избежать конфликтов при совместной работе над документами, Wizard предоставляет функцию сравнения версий документов. Если кто-то вносит изменения в документ, другие пользователи получают уведомление о том, что документ был изменён.
• Режим чтения: при использовании проектора для демонстрации технических решений рекомендуется использовать режим чтения, который показывает только содержимое документа.
• Поиск документов: позволяет быстро находить нужные документы по их заголовкам. Планируется добавить функцию полнотекстового поиска.
• Поддержка LDAP: многие компании используют LDAP для централизованного управления учётными записями сотрудников. Wizard поддерживает интеграцию с LDAP, позволяя легко подключаться к корпоративной системе учётных записей.
• Другие функции: включают поддержку вложений документов, совместное использование, статистику, сортировку документов, управление шаблонами, комментарии и уведомления.

Демонстрация функций

Более подробную информацию о функциях можно найти в Wiki проекта.

О коде

Проект разработан с использованием фреймворка Laravel. Текущая версия фреймворка обновлена до последней версии 5.8 (первоначально была 5.4). Чтобы повысить эффективность разработки и сохранить простоту архитектуры, в проекте избегают использования лишних внешних компонентов, предпочитая использовать встроенные компоненты Laravel, такие как Authentication, Authorization, Events, Mail и Notifications. Это делает проект подходящим для изучения Laravel начинающими разработчиками.

Установка

Поддерживаются два способа установки: через Docker и вручную.

Установка через Docker: подробные инструкции доступны на Docker Hub mylxsw/wizard.

Ручная установка: для новых пользователей необходимо выполнить инициализацию базы данных.