Внутренняя документация, которую никто не читает. Как сделать, чтобы читали (на примере ONLYOFFICE Workspace)

Автор: Иван Богданов, Технический писатель 

Когда я пришел в компанию, главной моей задачей была документация. Точнее, та каша, в которую она к тому времени превратилась. Часть статей писали люди, ушедшие за несколько лет до меня, и спросить, что там имелось в виду, было уже не у кого. Форматирование местами выглядело так, что глаз цеплялся за оформление вместо смысла, и читать это было физически тяжело. Хуже всего дело обстояло с систематизацией, статьи лежали как попало, и новичок успевал отчаяться, пока добирался до нужной.

С тех пор поменялось многое. Отдел писателей вырос, появились единые шаблоны статей, и они заметно упростили жизнь и авторам, и тем, кто потом вычитывает текст. За эти годы я хорошо понял, насколько документацию недооценивают. Толковый регламент или гайд экономит чужое рабочее время, и чем крупнее компания, тем ощутимее набегает эта экономия с каждого внятного руководства. McKinsey Global Institute ещё в 2012 году оценивал, что офисный работник тратит на поиск внутренней информации и нужных коллег почти пятую часть рабочей недели, и с тех пор внутренних систем у компаний стало только больше. Отдельно стоит упомянуть онбординг, т.к. когда новичку есть что почитать по процедурам в компании, он осваивается быстрее и нервничает меньше, ведь не приходится дёргать коллег вопросами по любому пустяку.

Документация нужна не только для поиска решений. Она ещё и отвечает на вопрос, с кого спрашивать за ошибку. Одно дело, когда инженер ошибся, потому что не знал, как правильно. Совсем другое, когда под рукой лежал подробный регламент, а человек всё равно сделал по-своему. Спрос в этих случаях разный.

Всё это работает, только пока документацию открывают. Открывают её, правда, далеко не всегда, и знакомый каждому дежурному сценарий объясняет почему. Идёт инцидент, сервис лежит, в рунбуке по восстановлению сервер называется так, как назывался восемь месяцев назад, и сорок минут уходит не на починку, а на выяснение, где инструкция врёт. Можно, конечно, сказать, что просто сотрудники ленивы и безответственны, оттого не пишут и не читают, но чаще документацию забрасывают не от лени, а потому что она либо неудобна в использовании, либо низкого качества.

Два кита документации

Удобство

Если, чтобы поправить один абзац, надо склонировать репозиторий, завести ветку, вспомнить разметку Markdown, дождаться сборки и провести изменение через ревью, то писать будут только те, кто и так живёт в этом процессе, т.е. инженеры. Документацию про найм, командировки, поддержку клиентов или юридические нюансы при таком пороге не напишет никто, и она либо не появится, либо растечется по личным заметкам, гугл докам и сообщениям в чате.

Качество

Документ может быть прекрасным, но если он лежит там, куда человек по своим делам не заходит, или поиск по двум словам его не находит, или он один раз соврал, дальше его просто не открывают. Самое разрушительное тут именно враньё. Один уверенно неверный документ обесценивает десять верных рядом, потому что человек теряет доверие ко всей базе сразу и возвращается к привычке спрашивать коллег.

Историю правок при этом ведёт почти любая платформа, та же вики покажет, кто создал документ и кто его менял. Только это сведения не то чтобы очень полезны, они скорее о  прошлом. Автор документа и владелец, отвечающий за его актуальность сегодня, часто разные люди, автор мог сменить отдел или уволиться. Кто пересматривает документ и когда пора это сделать, ни одна платформа за вас не решит, и устаревшее сама не удалит. Если документацией никто не занимается как процессом, то её не спасёт ни вики, ни редактор, ни самый удобный поиск. Инструмент не может заменить дисциплину. Дальше речь только про ту часть задачи поддержания документации, которую инструмент может решить.

Почему мы сами на MkDocs

Наша клиентская документация живёт в MkDocs, и менять это мы пока не собираемся. Пишут её технические писатели, которые и так весь день в Git, документы версионируются вместе с кодом, проходят ревью и сами собираются в статический сайт. Причём руками пишутся только сами инструкции. Часть материалов генерируется из Ansible-плейбуков, и делает это связка агентов, про которую мы подробно писали отдельно, статьи по развертыванию панелей маркетплейса собираются по актуальным плейбукам без участия человека. Пока описание живёт рядом с кодом, такая связка работает сама, и это ещё одна причина не тащить инженерную доку в визуальный редактор, автогенерация оттуда не достаёт.

Внутренняя дока, которую пишут далеко не только писатели или инженеры, живёт отдельно, в XWiki. Так сложилось исторически и поначалу её в основном держали техписы и руководители отделов, а также наиболее мотивированные сотрудники. Сама вики интуитивная, однако со страницами была беда, вёрстка получалась такой кривой, что работать с готовым текстом подчас было тяжело, особенно если статьи делались спешащими сотрудниками. Положение изменили нейросети. С ними готовить внутренние гайды стало заметно проще, и в базу потянулись обычные сотрудники, каждый по своей теме. Клиентской документации это тоже коснулось, черновые переводы на другие языки у нас делает отдельный агент, как он устроен и где ошибается, мы разбирали отдельно, финальная вычитка в любом случае остаётся за людьми. 

Поэтому дальше речь пойдёт про ONLYOFFICE Workspace. Он закрывает ту же задачу, что у нас закрывает XWiki, базу знаний, которую наполняют люди разных ролей. Разница в том, для кого это написано. Своя вики оправдана, когда есть кому её поднять и поддерживать. ONLYOFFICE Workspace это путь для тех, у кого такой команды нет, а готовая платформа со знакомым редактором и почтой, проектами и CRM рядом нужна уже сейчас.

Решение это далеко не для всех. Крупной компании с выделенной инфраструктурной командой Workspace тесен, там нужны единый вход, кластеризация и глубокие интеграции, и такие компании берут Confluence или строят своё. Команде из пяти человек он избыточен, платформа просит от восьми гигабайт оперативной памяти, и под десяток документов их не оправдать. Его аудитория это компании, где на всё хозяйство один системный администратор, техписов нет, а данные обязаны лежать на своём сервере. Причём дело не столько в размере, сколько в руках. Бывают компании и на полторы сотни человек с одним админом, им тоже подойдёт. Для такой команды главная ценность даже не редактор, а то, что один человек за вечер одним скриптом поднимает весь контур сразу, документы с правами, календарь, при желании почту и проекты, и дальше это хозяйство не требует отдельного смотрителя.

Что такое ONLYOFFICE Workspace и что с ним происходит прямо сейчас

ONLYOFFICE Workspace в самостоятельной сборке это набор веб-приложений на одном сервере. Ядро редакторов это ONLYOFFICE Docs (бывший Document Server), а вокруг него модули из ONLYOFFICE Groups, как с версии 11.0 называется бывший Community Server под лицензией Apache 2.0, сами редакторы при этом живут под AGPL v3. Сюда входят Документы, Проекты, CRM, Календарь, модуль Сообщество с блогами и форумами, плюс отдельно Mail Server, мессенджер Talk и панель администрирования Control Panel.

О закрытии облачного ONLYOFFICE Workspace компания объявила в декабре 2025 года, а в марте 2026 отключила его окончательно и перевела пользователей на DocSpace, новый флагман с организацией работы вокруг «комнат». Самостоятельная сборка Workspace для своего сервера при этом никуда не делась, её по-прежнему собирают в пакеты и обновляют, и речь в статье именно про неё. DocSpace заточен под совместную работу с документами в комнатах и за пределы документов почти не выходит. Самостоятельный Workspace остаётся самым функциональным вариантом, где база знаний это лишь один модуль рядом с почтой, проектами и CRM.

Как собрать из Workspace базу знаний

Если вам нужна именно вики, лучше понять это до установки. Специализированные движки с деревом страниц и настоящей перелинковкой существуют, о них я скажу ниже, в разделе про слабые места.

Сама установка платформы это одна команда официального скрипта.

wget https://download.onlyoffice.com/install/workspace-install.shsudo bash workspace-install.sh

Базу знаний собирают в модуле Документы, и его название стоит понимать буквально. Это система управления файлами, а не вики. Дерева страниц, автоматических wiki-ссылок и обратных ссылок здесь нет, все связи между документами расставляются руками. Роль оглавления берёт на себя стартовый документ, из которого ведут ссылки на разделы.

Раз навигацию не построит движок, её приходится закладывать в саму структуру. Выручают плоская иерархия и предсказуемые имена. Папки верхнего уровня под крупные темы, вроде Онбординг, Процессы, Регламенты и Шаблоны, стартовый документ со ссылками на них, и глубже двух уровней лучше не закапываться. Документ, потерянный в подпапках, ничем не отличается от ненаписанного.

Права раздаются на папки, и в этом больше пользы, чем кажется. Доступ настраивается один раз, а дальше каждый новый документ внутри папки наследует его сам, возиться с отдельными файлами не приходится. Схема по ролям ложится на папки естественно. Всем сотрудникам чтение, каждому отделу редактирование своей папки, стажерам одни комментарии. История версий есть у каждого документа, и это первое лекарство от гниения базы. Видно, кто и когда правил, и можно откатиться. Чтобы документ не протухал молча, мы держим в его шапке короткий служебный блок.

---Владелец: команда поддержкиОбновлено: 2026-06-20Пересмотреть до: 2026-09-20Статус: актуально---

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

ONLYOFFICE Docs по умолчанию требует JWT-токен для встраивания редакторов, и при ручной настройке за обратным прокси одна из самых частых проблем это рассинхрон секрета между Docs и панелью, после чего редактор молча не открывается, без внятной ошибки в интерфейсе. К базе знаний это отношения не имеет, но времени на установке съедает порядочно.

Исторически открытая Community-редакция Docs упиралась в 20 одновременных подключений, и для компании побольше это был потолок, толкавший сразу к платной редакции. Обходили его кто как мог, на форуме Nextcloud до сих пор живёт тема со сторонними сборками, где лимит поднят кустарно. В ONLYOFFICE Docs 9.4, релиз от 19 мая 2026 года, этот лимит из Community убрали, заодно свернув архитектуру в один процесс и убрав из стандартной установки зависимости от RabbitMQ и внешних баз данных. Снятие лимита видно и в самом коде, обзор на it-connect.tech указывает на конкретный коммит в GitHub. Для базы знаний на полсотни человек старая причина брать Enterprise ради лимита подключений отпала.

Вечер одного администратора

Типовой сценарий выглядит так. Компания на полсотни человек, весь технический штат это один системный администратор. Задача от руководства звучит буднично. Нужно место для внутренних инструкций, чтобы поддержка и кадровики писали сами, данные лежали на своём сервере, а обслуживание не съедало ничье время. Я прогнал этот сценарий на тестовом портале от начала до конца.

Развёртывание заняло меньше часа. Образ из маркетплейса, мастер первичной настройки, пароль администратора, язык и часовой пояс. Почтовый модуль можно не ставить вовсе, корпоративная почта у такой компании обычно уже есть, а тащить второй почтовый сервер ради базы знаний незачем.

Отдельно я проверил миграцию под нагрузкой. Взял реальную базу документации нашего маркетплейса, больше тысячи файлов Markdown и картинок, разложенных по полутора десяткам тематических папок, от панелей управления до баз данных, и залил её в портал целиком, через загрузку в браузере. 

Структура папок доехала как есть, ничего не рассыпалось и не переименовалось, а вся заливка заняла меньше десяти минут. 

Дальше выяснилось существенное ограничение. Markdown портал хранит и находит по именам, но открыть такой файл в браузере не даёт вовсе, предлагает только скачать. Редакторы понимают форматы Office, PDF и простой текст, а md для них чужой тип. Нормальный путь это конвертация в docx перед заливкой, одной командой через pandoc.

find . -name '*.md' -exec sh -c 'pandoc "$1" -o "${1%.md}.docx"' _ {} \;

Markdown при этом никуда не выбрасывается, он остаётся инженерам в Git, а в портал уезжает читаемая docx-копия. Ещё одна мелочь, способная съесть время и нервы, это защищенные паролем PDF.

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

Ещё около часа занимает скелет базы. Папки верхнего уровня из прошлого раздела, стартовый документ со ссылками на них, права по ролям. Поддержка редактирует свою папку, кадровики свою, читают все, а стажерам открыты только комментарии, пусть спрашивают непонятное прямо в документе, а не в личке у старших. В Шаблоны кладётся болванка регламента с той самой служебной шапкой.

Дальше администратор из процесса выходит. Аварийную инструкцию по восстановлению сервиса пишет уже сотрудник поддержки. Он открывает болванку, заполняет готовые разделы, симптомы, диагностика, шаги, кого будить, и включает режим рецензирования. Второй дежурный проходит по тексту, поправляет имена хостов, добавляет пропущенный шаг с проверкой очереди, и автор принимает правки по одной. Спор о том, будить ли ночью администратора баз данных, закрывается в комментарии к конкретному абзацу и остаётся в документе, а не в личке мессенджера, где его через месяц никто не найдёт.

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

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

Ограничения

Workspace это не вики, поэтому перелинковка ручная, а полнотекстовый поиск по содержимому документов слабее, чем у инструментов, заточенных под базу знаний. Diff по тексту не такой наглядный, как построчный в Git. Ресурсов платформа ест ощутимо больше статического сайта, и поднимать ради десятка страниц целый Workspace избыточно.

Из того же портрета аудитории видно, кому он не подойдёт. Если вся ваша документация инженерная и версионируется вместе с кодом, оставайтесь на docs-as-code и не тащите её в Workspace ради одного инструмента на всё. Если вам нужна именно вики с деревом страниц, посмотрите на специализированные движки, вроде Wiki.js, BookStack или Outline. Они self-hosted, дают настоящие wiki-ссылки и поиск получше, и как чистая база знаний нередко обходят Workspace. Confluence и Notion мощнее по возможностям организации, но Notion живёт только в облаке, а самостоятельный Confluence Data Center стоит заметных денег и данные при облачном варианте уходят с вашего сервера.

Сильная сторона Workspace проявляется в одном сценарии. Когда писать и читать документацию должны люди разных ролей, нужен полноценный офисный редактор с совместимостью по форматам Word и Excel, и при этом данные обязаны остаться на своём сервере. Тогда визуальный редактор плюс права на папки плюс история версий закрывают задачу без обучения людей разметке, а бонусом рядом оказываются почта, проекты и CRM, если они нужны.

Искусственный интеллект

ONLYOFFICE добавил в редакторы ассистентов на основе искусственного интеллекта для черновиков, переписывания и перевода, а в DocSpace заявлены агенты. Для базы знаний это приятная мелочь, но второстепенная. Ассистент причешет формулировку, однако трение записи и чтения он не убирает, а врущий документ останется врущим, пока его не пересмотрит человек. Плюс самостоятельной сборки в том, что подключение внешних компаний-разработчиков моделей вы контролируете сами и можете не включать его вовсе, что для внутренних документов часто и разумнее.

Что заставляет документацию читать

Инструмент это половина дела, вторая половина это несколько привычек, которые у нас заметно влияют на то, открывают базу знаний или нет.

1. У каждого документа есть владелец и дата пересмотра. Без этого документ медленно протухает, и спросить не с кого.

2. Документация лежит там, куда человек заходит и так. Ссылка из чата, из таск-трекера, из письма с онбордингом. Отдельный мир, в который надо специально идти, проигрывает всегда.

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

4. Устаревшее удаляют или явно помечают, а не оставляют «на всякий случай». Один врущий документ дороже, чем десять отсутствующих.

5. Шаблоны снижают порог входа. По готовой болванке регламент пишется в разы быстрее, чем с чистого листа, и человек охотнее садится за него.

Где здесь хостинг

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

Выводы

Идеальной документации не существует, и гнаться за ней бессмысленно. База знаний это не проект с датой сдачи, а длящийся процесс, документы устаревают быстрее, чем пишутся новые, и нормальное её состояние это «местами неполная, но живая». Инструмент в этом процессе отвечает за малое. Документацию читают не потому, что под неё выбрали правильную платформу. Читают её там, где дописать абзац недолго, нужный документ находится с первого запроса, а устаревший не задерживается. Всё это привычки команды, и никакой софт их не заменит.

Про сам Workspace тоже стоит помнить, что он в переходном состоянии. Облачную версию закрыли, ставка сделана на DocSpace, и куда сместится самостоятельная сборка через год, заранее не скажешь, так что закладывайте возможность миграции и держите бэкапы. За рамками статьи осталось много прикладного, от резервного копирования и переноса портала до интеграции с LDAP, единого входа и масштабирования под сотни пользователей.