Меня беспокоит наша база знаний с документацией по нашему ПО на сайте. Она выглядит не особо и содержит ряд фундаментальных проблем, которые портят жизнь как разработчикам, так и пользователям.
Сайт Софтонит сделан на Битрикс, и изначально мы выбрали встроенный в эту платформу механизм для создания базы знаний. Это было в 2016 году, и на тот момент казалось, что всё выглядит хорошо и в целом всё удобно и классно.
Надо зайти и изменить статью? Открываешь админку сайта, заливаешь картинки, добавляешь текст статьи на сайте, и она сразу же отображается для клиентов. Удобненько (как тогда казалось).
Время идет, всё меняется, и вот уже ты видишь проблемы со старым подходом:
- В Битрикс оказывается неудобный встроенный редактор статей. Редактируешь статью, сохраняешь, в админке она выглядит так, а для пользователей верстка едет. Переключаешь в режим HTML, а там левые теги. Приходится их вычищать.
- Понимаешь, что есть проблемы с добавлением и изменением изображений. Нельзя вставлять изображения в статью из буфера обмена. Также изображение добавляется в медиабиблиотеку, а стандартный редактор использует уже изображение оттуда. В целом это работает не очень быстро. Процесс обновления одного скриншота превращается в квест из девяти кругов ада: сделай скриншот, сохрани файл, зайди в админку, открой медиабиблиотеку, загрузи файл, скопируй ссылку, вернись в статью, вставь ссылку… Хочется просто перетащить картинку в редактор, а вместо этого ты тратишь 10 минут на рутину. А если нужно поменять 20 картинок? Это просто воровство времени у команды разработки. Жесть.
- Плохой поиск. Прям очень. Было пару раз, что поиск отваливался в базе знаний после обновления Битрикс, и за мной ходила менеджер по продажам и говорила, как ей показывать какие-то фичи клиентам и отвечать на их вопросы, если она не может ничего найти в базе знаний. А изменить ты особенно ничего не можешь. Не будешь же править Битрикс и искать, в чём косяк. Потом это, конечно, всё восстанавливалось со следующими обновлениями, но осадочек от этого остался.
- Но всё это мелочи по сравнению с главной проблемой, которая меня бесит: документация живёт своей жизнью, отдельно от кода. Разработчик выкатил фикс, а документация осталась старой. В итоге клиент читает одно, а в программе видит другое. Это прямой путь к потере доверия. И именно этот разрыв стал для меня последней каплей.
Я задумал на сайте Софтонит заменить старую документацию и использовать концепцию Docs-as-Code. Что это вообще за концепция?
Всё просто — работаем с документацией так же, как и с исходным кодом программы. Заводим папочку «docs», и все скриншоты и файлы в текстовом формате (обычно это markdown) пишем и изменяем тут же, а потом пушим всё в Git. При пушах срабатывает линия сборки, которая автоматически разместит документацию на нашем сайте. При таком подходе мы получим:
- Версионирование документации. Удобно видеть версии документации.
- Документация соответствует коду, который изменяется, и она обновится тогда, когда мы выпустим релиз. Т.е. документация следует за кодом (но тут всё зависит от того, как вы настроите линию сборки).
- Можно использовать любимые markdown-редакторы. Лично мне нравится редактор Visual Studio Code и плагин для Markdown. Оно умеет и из буфера файлы вставлять в текст, и даже есть свой линтер для формата Markdown (подчеркивает желтым, если ты что-то не так делаешь в оформлении текста).
- Мы отделяем текст документации от оформления этого текста на сайте. Есть куча генераторов статических сайтов, которые потом используют нашу доку, это всё сопрягается вместе, и мы получаем красивые мини-сайты с нашими markdown-файлами. Всё это работает очень быстро и выглядит очень круто. Там и встроенный поиск, и красивые стили, и адаптивность и т.п.
Но это всё теория! 🙂 Легко всё на бумаге, но вот внедрить всё это будет непросто. У меня пока нет готового решения.
Я пока не определился, что использовать в качестве генератора статических сайтов и как организовать сборку для всего нашего ПО. Есть такие инструменты, как Diplodoc, Docusaurus, Hugo, MkDocs или Gatsby, и они часто применяются для таких целей. Но на каком остановиться, пока не ясно.
В общем, начинается эпопея под названием «Убираем старое и ставим новое» 🙂
Это первая часть серии статей по разворачиванию новой базы знаний и изменению старых механизмов. Буду держать в курсе, что выберу и как это потом настрою.
А на чём живёт ваша документация? Тоже страдаете, как мы сейчас, или уже нашли самый лучший инструмент для документации?
PS: Продолжение следует…