Универсальный документатор

Документирование - есть важная часть в жизни. Давайте разберемся, что такое это и с чем его едят.

Под личными заметками я подразумеваю:

• Личная база знаний - по софту, примерам кода, рецептам, и т.д.
• Дневник.
• “Быстрозаписи” - фактически мусорный текст, который был создан максимально быстро, чтобы не забыть о пришедшей в голову идее или свалившейся на нее же, бедную, задачу.
• …и т.д. и т.п., каждый может придумать свой тип данных.

Под рабочей документацией я понимаю:

• Инструкция по работе с приложением для пользователя или администратора.
• Сборник бизнес-функциональных требований (БФТ) и высокоуровневого дизайна (HLD).
• Сборник техзаданий (ТЗ) и низкоуровневого дизайна (LLD).
• …и все это приправлено различными схемами и картинками.

Найти хороший инструмент чрезвычайно сложно под каждую конкретную задачу. Например, для личных заметок и базы знаний хорошо подойдут Joplin, Notes.app (который эполовский стандартный заметочник), Evernote, QOwnNote… Да в принципе, очень много их, вплоть до org-mode плагинов для Emacs’а и штуки под названием nb. Выбирай на любой вкус и требования.

Для рабочей документации фраза “все средства хороши” неприменима, потому что нужно, чтобы было удобно, красиво и “копипастно”, а еще лучше - если оно еще и “визивигно” (WYSIWYG). И тут на помощь приходят только:

• MoinMoin, который очень больно администрировать в плане работы с приложением на уровне ОС. Да и WYSIWYG редактор там тоже “с приколами”.
• MediaWiki/Dokuwiki с WYSIWYG плагинами, но там свои приколы с конвертацией wiki-синтаксиса туда-сюда. Будет ехать в каждом втором или третьем случае, принося фрустрацию.
• Confluence, который мало того, что платный, так еще и недоступный для россиян к покупке.
• Можно тут вспомнить open source штуку под названием XWiki, но работать с ней около года назад было больно, ибо она неповоротлива. Поэтому ее я даже не рассматриваю, хотя под требования к системе для работы с документацией она вполне подходит. ЕМНИП, это единственное ПО вообще из опенсорсных, которое позволяло делать цветными ячейки таблицы.

Но я был бы не я, если бы не нашел что-то такое, что подошло бы подо все (и под личные заметки, и под рабочую документацию). Правда, с некоторыми оговорками. Итак, встречайте, Outline Wiki.

Если не открывается - попробуйте через прокси или VPN ¯⧹_(ツ)_⧸¯.

В Outline есть в принципе все, что нужно любому, даже особо требовательному пользователю. Софт умеет:

• Группировать страницы по подразделам на практически неограниченную глубину.
• Шарить отдельные страницы или даже разделы с подразделами и страницами, причем не только внутри приложения (есть простенький ACL в виде RBAC, Role-Based Access Control, просто накидываете доступ только для чтения или для чтения и записи пользователям и группам), но и по ссылке любому, у кого она есть.
• В историю изменения страницы.
• Автоматически генерировать и отображать оглавление.
• Показывать, кто и когда эту страницу смотрел, а также кто ее сейчас редактирует, вплоть до совместного Live-редактирования.
• Удалять страницы сначала в “корзину”, чтобы можно было легко восстановить.
• (Уже, с последней версией) Отображать схемы и диаграммы Mermaid.
• Русский язык, API, поддержка темной и светлой темы оформления (с синхронизацией с ОС).
• Возможность использовать как WYSIWYG для тех, кто неискушен, так и Markdown для тех, кто как раз очень даже искушен.

Кстати, про WYSIWYG и Markdown - оно сделано, на мой взгляд, просто идеально! Человек, независимо от того, кто он - менеджер ли, разработчик ли, сможет в одном приложении работать одинаково эффективно. Привыкли использовать CTRL/CMD+B для выделения текста жирным - пожалуйста. Любите Markdown’овские звездочки - нет проблем. Мышетыкатель - тоже все ок, над выделенным текстом сразу появляется панель форматирования. Вставка картинок из буфера тоже работает отлично.

Но, конечно же, есть и ложка дегтя:

• Нет поддержки тегов. Совсем. Вообще. Подписываемся и ждем. Лишь бы не каличный frontmatter из комментов…
• Нет поиска по быстрым командам ("/" в пространстве ввода текста) по любым языкам, кроме английского. Причем, если у вас не английский, даже ввод английского названия команды работает криво.
• Нет упоминаний. Все привыкли к @-касту пользователей куда бы то ни было, а тут - индейское национальное жилище вам, а не касты. Как минимум пока что.
• Тяжело в поднятии. Начнем с того, что оно предлагает аутентифицироваться только через OIDC (OAuth) или Slack/Google/Azure. Встроенного функционала работы с пользователями нет. А закончим тем, что загружаемые файлы оно хранит в S3, то есть либо заносим денежку условному Яндексу, либо поднимаем minio (а там тоже есть свои подводные камни). А еще написано на NodeJS. Вспоминается сразу тот самый мем:
  

Однако, несмотря на все недостатки, я использую оный уже почти 4 месяца для личной документации и внедряю Outline на работе. Пока что всем нравится, а недостающий функционал в виде тегов, надеемся, приедет в ближайшее время.