Сервис, аналоги которому ещё поискать нужно или «Портал руководств, доков, wiki и справок»
Речь о Документерре — платформе для централизованного создания разного вида документации, то есть профессиональном инструменте для технических писателей. Я даже не представлял насколько всё сложно в этой сфере и что это из себя представляет. Классный и редкий профессиональный инструмент достоин обзора.
Всем привет! Меня зовут Вадим, и я пишу о полезных сервисах и инструментах: рассказываю чем они хороши и делюсь своим опытом в формате обзоров.
Бывает такое: пойдёшь в лес за ёлочкой, а там и щука волшебная, и дом-полная чаша, и заяц отличный, со шкурой и шкварками, и приключения горой.
Вот и у меня получилось что-то похожее: шёл и на поиски систем формирования и управления базами знаний, а нашёл... Систему формирования и управления базами знаний, только с «изюминкой». Оказалось, Документерра — нечто гораздо более сложное, да и основная задача у сервиса несколько иная: это не только и не столько про создание и управление базами знаний, сколько про профессиональную разработку различных видов документации.
Оглавление:
1. Что за Документерра?
2. Это просто редактор?!
3. Это про базы знаний или...?
4. Функциональность
5. Тарифы
6. Вывод
Что за Документерра?
Это платформа для централизованного создания документации разного вида, характера и применения:
- Руководства пользователя (в виде сайтов, PDF, DOCX, CHM, …)
- Внешние базы знаний (публичные и с закрытым доступом)
- Вики-сайты для техподдержки
- API документация (OpenAPI/Swagger)
Оказывается, устоявшегося названия такого вида платформ в русском языке нет — я вообще целый мир для себя открыл, изучая Документерру, техписов и вот это всё.
Создатели платформы предлагают использовать термин «доки» для платформ всех этих видов документаций разом.
Платформа российская, вендор — аккредитованная ИТ-компания, датацентры в России. А это в современных реалиях снимает массу вопросов.
Это просто редактор?!
Это намного больше, чем редактор — это как специализированная CMS для документации, я нисколько не преувеличиваю.
У платформы есть обширное API для автоматизаций и интеграции с CI/CD пайпланом, встраивания виджета поиска в своё приложение или сайт, создания многоязычных сайтов документации, отображения контекстных всплывающих подсказок в веб-приложениях, авторизации читателей через одноразовые токены или SSO, и так далее. Кроме того, можно интегрировать сторонние JavaScript библиотеки и сервисы для расширения функций.
А с точки зрения создания контента — это сильные фичи командной работы: статусы, ответственные, история изменений со сравнением версий, отчёт по готовности документов с распределением по пользователям/проектам/статусам, права пользователей, оповещения об изменениях статей, процесс рецензирования.
Что и как заменит Документерра?
Если кто-то не очень знаком (как я, например) с миром разработки документации, посмотрите на перечень платформ и ПО, заменяемых Документеррой, может быть увидите что-то знакомое. Специалистам тоже интересно будет взглянуть.
Я разбил эту «заменяемость» по нескольким сегментам и двум критериям — что именно и как именно может заменить Документерра.
Профессиональные системы создания документации для технических писателей
Какие:
- MadCap Flare
- Adobe Robohelp (вот об этом продукте я знал!)
- Dr.Explain
- HelpNDoc
Как:
- Поддержка Технологии Единого Источника — в проекте создаётся контент, потом из него формируются все нужные форматы и вариации (есть блоки с условной видимостью)
- Повторное использование контента, чтобы быстрее обновлять всякие дисклеймеры и типовые инструкции — в одном месте поменял, везде обновилось. Что-то вроде компонентов в Figma
- Централизованное хранение скриншотов, чтобы быстрее обновлять сразу везде
- Командная работа с другими отделами — программисты могут делать ревью, добавлять комменты к блокам текста, при этом можно правами ограничить возможно писать и менять текст, ибо программисты пишут... не очень хорошо и техписы (подрезал термин у профессионалов отрасли) не любят, когда программист сам начинает править топики
- Экспорт в разные форматы: PDF, CHM, DOCX, RTF, HTML5 WebHelp, чистый HTML
- При экспорте в PDF/DOCX, можно использовать Word-файл как шаблон — например, настроить рамку по ГОСТ в шаблоне и экспортировать документы с рамкой. На мой взгляд — мегаудобный функционал: не подгонять контент под шаблон, а шаблон сам принимает и адаптирует контент
- Кроме огромного количества функций непосредственно для написания контента, Документерра предлагает размещать на их платформе онлайн-версии справочных систем. Можно делать многоверсионные руководства (например, для ПО, которое выпускается версиями и надо держать доступными несколько версий доков). Есть аналитика поисковых запросов читателей, чтобы понимать что именно и как они искали. Есть очень крутой поиск, практически как у Google — с поддержкой недописанных слов, опечаток, словоформ, и даже (здесь я надолго залип от открывшегося волшебства!!!) с возможностью указания рекомендованной статьи для конкретного запроса! И эта статья будет в спецблоке в результатах поиска.
Есть экспорт в PDF отдельных статей для читателей с настройкой автором шаблона для такого экспорта. Встроенная система прав на уровне групп и отдельных пользователей, с поддержкой SSO. То есть платформа предоставляет не только инструменты для создания, но и платформу размещения и улучшения доков
Системы управления базами знаний
Какие:
- Confluence
- Teamly
- EvaWiki
- Бесплатные вики-системы, на которых строятся сайты баз знаний
Как:
- В случаях использования системы для создания внешней базы знаний или сайта документации, Документерра предлагает более удобные решения — публикация сайта с разделами и документами без необходимости организовывать приглашения, настройку прав доступа и так далее
- В ситуации, когда внутренняя база знаний — это некий побочный продукт централизации документации. В плане баз знаний фокус функций Документерры сосредоточен на внешних базах знаний для клиентов и партнёров. Но вполне можно создавать и внутренние документы — просто вы их не публикуете, оставляя в виде проектов. Или же публикуете, внедряете SSO для сотрудников, раздаёте права доступа к таким публикациям только сотрудникам, остальные же будут читателями
Инструменты публикации API-документации
Я знаю только малую толику (оказывается 🤔) таких инструментов, в большей же части совсем не «волоку», поэтому обратился в поддержку сервиса, ребята соединили меня с «центром» и я узнал ещё больше (-:
Какие:
- Статические сайт генераторы: Jekyll, Hugo, etc.
- Опенсорсные решения на своих серверах: Redoc, RapiDoc, Swagger UI, etc.
- SaaS-решения: Redocly, ReadMe, DeveloperHub, Stoplight, etc.
Как:
API доки можно делать по-разному, кому как нравится, кто как привык и где как принято.
- Самый удобный вариант — писать в формальных форматах типа OpenAPI (ранее - Swagger). Из формального описания в виде текстового JSON-файла можно получить готовый веб-интерфейс для пользователя, что-то вроде: petstore.swagger.io.
Суть в том, что иногда автосгенерированного UI недостаточно, оно и понятно, в общем-то. Вот здесь Документерра рулит — берём наш OpenAPI файл определения, импортируем в Документерру и получаем такой же красивый UI, только лучше — в один онлайн-гайд можно импортировать много определений и каждое будет отдельной папкой в дереве содержания. При этом, в том же гайде можно создавать и обычные текстовые топики. В итоге получается не разрозненный набор API-доков, изолированных один от другого, а все API-доки находятся в одном UI с единой навигацией и поиском сразу по всем документам: API, база знаний, руководства пользователя, спецификации и так далее. Чудо? Чудо! - Другой способ создания API-доков: написание топиков вручную. Это приходится делать, когда разработчики не готовы писать определения в формальном формате типа OpenAPI. Тогда техписатель может создать в Документерре API-доки вручную, для этого в редакторе есть готовые кусочки контента (сниппеты) специально для такого вида доков: таблицы методов и параметров, коды ответов и тому подобные
- Для получения максимальной пользы от Документерры, имеет смысл размещать в ней не только API доки — для этого можно и бесплатные инструменты использовать (хотя тогда придётся хостингом самому заниматься). Если уж делать онлайн-портал документации, то делать там и API, и суппортную вики, и гайды, и инструкции
Суппортные базы знаний
Какие:
- Zendesk
- Freshdesk
- Юздеск
- И практически все остальные *desk, в которых прицепом к тикет-трекингу идёт функция публикации статей
Как:
- Когда статей становится много, системы, подобные перечисленным, перестают справляться на уровне удобства и расширяемости. Либо возникает ограниченное количество уровней вложенности категорий, либо отсутствие возможностей повторного использования контента, либо отсутствие централизованного хранения скриншотов (при обновлении надо искать все статьи и в каждой менять — и это отдельный адЪ), и так далее
- Нередко такие системы не дают возможности выгружать целиком проект или набор статей в один PDF — можно только одну статью выгрузить, а и то и страницу (но это, правда, совсем редкость). А ведь порой нужен целый раздел
- Фокус таких систем всё же на тикетах, а доки — побочный инструмент. В итоге редактор контента часто очень ограниченный, истории изменений топика нет (а в Документерре, на секундочку, она безлимитная), рецензирования нет, и так далее — масса неудобств, если честно. Все эти вещи часто становятся видны только через год-два после начала ведения суппортной вики в такой системе
Это про базы знаний или...?
Из самой близкой именно мне функциональности в Документерре — базы знаний. Но! В том виде, в каком системы работы с БЗ использую я, то есть внутренней личной или корпоративной документации, Документерра не будет лучше Teamly или EvaWiki, это не её фокус. А вот внешние базы знаний — здесь, без разговоров, просто нет у Документерры в России конкурентов.
Поэтому в ситуации, когда приоритет — на документации и внешней БЗ, а не внутренней базе знаний, Документерра и Confluence хорошо заменяет. Вот прям классно: есть офигительный импорт из Confluence с автоматической обработкой около 30 разных макросов, включая Scroll Versions который любят техписы. А самое классное, что у ребят есть поддержка своих элементов, соответствующих почти всем макросам Confluence. Яркий пример — макрос Excerpt, он нужен для повторного использования кусочков контента. Так вот при импорте он превращается в их внутренний элемент Snippet, который делает то же самое. Конвертация элементов на лету при импорте!
Что хвалят пользователи в Документерре, по сравнению с Confluence:
- Гибкий редактор. Он визуальный, но с режимом HTML для особо сложных случаев
- Брендирование читательского UI — легко сделать портал под стиль своей компании, включая свой домен (хотя хостинг остаётся у платформы)
- Глобальный поиск и замена с поддержкой регулярных выражений
- Качественный импорт из DOCX, HTML, CHM
- Система перевода документации. Целый отдельный модуль для многоязычных доков — табличный редактор переводов, импорт-экспорт XLIFF файлов, интеграция с системами машинного перевода
Функциональность
Конечно, я просто не могу осилить, не будучи профессиональным техническим писателем, даже малой толики функций такого комбайна, хотя излазил практически всё нутро Документерры вдоль и поперёк.
Особенно понравились возможности кастомизации фронтальной части сайта-портала, на котором публикуются документы.
Поэтому я, по сути, «размазал» информацию о функциональности платформы по остальным разделам, здесь же покажу несколько скриншотов, чтобы можно было оценить «масштаб трагедии» 🙂 этого потрясающего сервиса.
Импорт:
Настройка портала:
Публикация документов:
Редактор:
Отчёты:
Тарифы
Не забывайте: Документерра — профессиональный инструмент, поэтому бесплатных тарифов, пусть даже и с урезанной функциональностью (а как её здесь можно урезать?), нет. На самом деле всё просто: нужен качественный профессиональный инструмент для зарабатывания денег? Вот он, пожалуйста.
Как видите, ровно три тарифа, основные отличия функциональности: количество страниц (500 на базовом, на остальных не ограничивается); объём файлового хранилища; подключенные модули.
Отдельно подключается модуль «Управление переводами», что вполне логично — если документация/wiki/руководства готовятся на одном языке, эта функциональность избыточна.
Вывод
Я очень уважаю и ценю профессиональные инструменты, созданные профессионалами для профессионалов. Неважно что это: пассатижи или редактор кода, нейросеть или нож.
Документерра — тот самый пример профессионализма во всём: от настроек портала и визуализации страниц для посетителей до процесса подготовки документации, её публикации и конвертации в различные форматы.
Да, это довольно узкая ниша, но технических писателей не так и мало, а профессиональных инструментов для них, как выяснилось, и вовсе кот наплакал. Тем ценнее каждый открытый сервис!
Что хочу отдельно отметить: внешний вид портала — вашу документацию будут читать живые (!!!) люди, а не только поисковые краулеры. Поэтому возможность настройки хорошего, приятного фронтенда — просто благодать и я даже больше скажу: не припомню сервисов, которые позволяют тонко и в широких пределах настраивать хоть что-то, кроме смены аватарки и выбора темы. В то время как в Документерре можно делать так:
Сервис крут и вызывает ощущение... добротности, надёжности и серьёзного подхода к делу. Очевидно, что разработчикам и основателям ценен не только сам продукт, но и его пользователи, это всегда внушает уважение!
Пользуйтесь на здоровье 🤘🏻
📋 Мои публикации о сервисах/ПО:
- Kaiten — российский таск-трекер c системой Service Desk
- Gerwin — нейросети на службе человека + экономия времени
- Пачка — корпоративный мессенджер для любых команд
- Shtab — управление проектами или «Trello на максималках»
- Яндекс Музыка — обновление айдентики и нейрорекомендации
- Adesk — cервис финансовой аналитики для бизнеса
- TeleChurn — анализ аудитории telegram-канала
Нужно протестировать ваш сервис и рассказать о нём?
Пишите мне в tg — @vadasl
Поддержите публикацию, просто поставив ей 💗
✦ Приходите в мой telegram-канал о полезных сервисах и инструментах.
Я делюсь опытом их использования и повышения продуктивности.
Пишу редко, но строго о полезном: