Больше года моя команда работала над новой версией «Управление IT-отделом». Сегодня я готов показать, что у нас получилось. Это не просто обновление, а полная пересборка продукта.
TL;DR: Выжимка
❗ Главное: Мы убили громоздкую связку «Проект → Процесс → Этап». Теперь есть только гибкие Проекты с настраиваемыми колонками (разделами), как в Trello или Jira. Стало на порядок проще и логичнее.
🔥 Права доступа: Полностью переписали RLS. Теперь доступ определяется участием в проекте, а не сложной иерархией подчиненности. Идеально для матричных команд.
📱 Мобильное приложение: Выбросили старое на технологиях 1С и написали новое с нуля на Flutter. Оно нативное, быстрое, и push-уведомления теперь работают как часы.
🤖 AI-ассистент: Встраиваем ИИ, который превращает технические комментарии инженера в вежливые ответы для пользователей и помогает структурировать задачи. Меньше рутины, больше дела.

👉 Подробнее на https://codeitdir.ru/other/uit-4-0-anonce/?utm_source=Telegram&utm_medium=social&utm_campaign=25972109
#РазборПродукта_КИД

Many-Notes: Простые заметки в Markdown на своем сервере.

Наткнулся на Reddit на небольшой, но очень интересный проект для тех, кто любит полный контроль над своими данными и ценит минимализм. Это self-hosted приложение для заметок Many-Notes.

TL;DR: Коротко о главном

💡 Что это? Опенсорсное web-приложение для работы с Markdown-записями, спроектированное с акцентом на минимализм и полный контроль над данными. Вы разворачиваете его у себя (self-hosted).

✅ Главная фишка: Использует базу данных (SQLite по умолчанию, но поддерживается MariaDB, MySQL и PostgreSQL) для продвинутых функций вроде многопользовательности и быстрого поиска, но при этом все заметки физически лежат в виде .md файлов. База нужна не для хранения текста заметок, а для метаданных, пользователей и индексации поиска.

🚀 Технологии: Написано на PHP, рассчитано на простую установку через Docker.

🤔 Кому зайдет? Небольшим командам или продвинутым пользователям, которым нужна своя база знаний с совместной работой, но без привязки к конкретному сервису.

Что под капотом? Ключевые возможности:

- Это не просто минималистичный блокнот — внутри полноценные инструменты для командной работы. Функциональность здесь серьезная:
- Многопользовательский режим и совместная работа: Можно заводить отдельных пользователей и давать им доступ к «хранилищам» (vaults). Это выводит инструмент из категории «личный блокнот» в категорию «командная база знаний».
- OAuth-авторизация: Поддерживается вход через GitHub, Google, Keycloak и другие популярные сервисы.
- Продвинутый редактор: Markdown + визуальный интерфейс (WYSIWYG), со сплит-панелью предпросмотра. Есть шаблоны, теги, поиск по обратным ссылкам, автосохранение.
- Быстрый поиск: Используется typesense для быстрого и отказоустойчивого поиска по заметкам. Но это отдельный сервис, его тоже нужно поднять.
- PWA (Progressive Web App): Приложение можно установить на рабочий стол или смартфон для более удобного доступа.

Полезные ссылки:

➡️ Репозиторий на GitHub: brufdev/many-notes

➡️ Обсуждение на Reddit: Тред в /r/selfhosted

А вы чем пользуетесь для ведения заметок? Предпочитаете облачные сервисы или self-hosted решения? Делитесь в комментариях.

https://codeitdir.ru?utm_source=Telegram&utm_medium=social&utm_campaign=25968122
#РазборПродукта_КИД

«Ты что, мне не веришь?» — как выходить из ловушек в диалоге с руководителем

Есть старая уловка: инспектор ДПС останавливает вас, говорит, что вы нарушили. Вы уверены, что нет, и начинаете спорить. В ответ он задаёт вопрос: «То есть ты мне не веришь?»
Разговор сразу уходит с уровня фактов на уровень отношений и статуса. И дальше спорить почти невозможно.

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

Ловушка 1. «Ты хочешь сказать, я не разбираюсь?»

Ситуация. Подчинённый предлагает более эффективный вариант. Руководитель переводит спор в плоскость «компетентности начальника».

Вы: Для нас нанять подрядчика будет дешевле, чем делать эти работы самостоятельно.
Руководитель: Ты хочешь сказать, что я в этом не разбираюсь и зря вообще предлагал свой вариант?

Как реагировать? Не спорить о компетенции, а подчеркнуть ценность данных.
Решение: Я уверен, что вы разбираетесь. Просто показываю расчёты и предлагаю сравнить варианты. Решать, конечно, вам.
Подмена: Спор о цифрах превращается в спор о компетентности.

Ловушка 2. «Ты не доверяешь моему слову?»

Ситуация. Руководитель передаёт информацию от партнёра или поставщика. Подчинённый проверяет и находит неточность.

Руководитель: Поставщик сказал, что эта система без проблем установится у нас.
Вы: Я проверил, и технически это не так. Потребуются дополнительные работы.
Руководитель: То есть ты не доверяешь моему слову и словам партнёра?

Как реагировать? Покажите, что проверка — не про доверие, а про снижение рисков. Решение: Я доверяю вам, поэтому и проверил слова поставщика. Вот, что показала проверка. Теперь можно обсудить риски и цену доработки.
Подмена: Вместо оценки фактов — вопрос личного доверия.

Ловушка 3. «Ты ставишь под сомнение мои приоритеты?»

Ситуация. Руководитель называет задачу «срочной», а подчинённый указывает на последствия для других проектов.

Руководитель: Срочно внедряем CRM, от этого зависит работа продаж.
Вы: Если мы начнём сейчас, есть риск сорвать плановую миграцию бухгалтерии.
Руководитель: То есть мои приоритеты ты считаешь неправильными?

Как реагировать? Признайте право начальника на приоритет, но верните его в поле выбора.
Решение: Приоритеты определяете вы. Моя задача — показать последствия. Если делаем А сейчас, то Б задержится на месяц.
Подмена: разговор о ресурсах превращается в разговор о «лояльности» к стратегическим целям.

Выводы

Все эти примеры сводятся к одному: разговор уходит из области фактов в плоскость статуса, доверия, авторитета. Если подчинённый начинает оправдываться или спорить в лоб, он проигрывает.

Гораздо эффективнее — спокойно вернуть диалог к данным и интересам бизнеса. Подчёркивайте, что финальное решение всегда за руководителем. Ваша задача — дать ему фактуру для выбора. В итоге вы не спорите с начальником, а помогаете ему принимать взвешенные решения.

Чек-лист: как выходить из провокационных ловушек

Что делать
✅ Спокойно возвращайте разговор в плоскость фактов и цифр.
✅ Подчёркивайте право руководителя на финальное решение.
✅ Формулируйте аргументы через заботу о бизнесе: «чтобы снизить риски», «чтобы не потерять сроки».
✅ Используйте переформулировки. Меняйте «Ты не доверяешь?» на «Я доверяю, поэтому проверил детали».

Чего не делать
❌ Не спорьте в лоб, не говорите «я прав, а вы не правы».
❌ Не оправдывайтесь. Фразы вроде «нет-нет, я вам верю, честно» ослабляют позицию.
❌ Не переводите разговор обратно в эмоции.
❌ Не теряйте фокус обсуждения. Цель — решение для бизнеса, а не выяснение отношений.
#Бизнес_КИД

Как понять, какие AI-модели действительно работают? Используем openrouter.ai

Если вы не хотите «читать в новостях хайп», а видеть реальную статистику по тому, какие AI-модели сейчас используют разработчики и компании — рекомендую заглянуть на https://openrouter.ai/rankings?view=trending

Что это?

- По сути, универсальный роутер для нейросетей. Можно в режиме чата попробовать практически любую популярную модель (GPT-5, Claude, Gemini, LLaMA и т.п.);
- В открытом доступе есть статистика использования каждой модели — видно, что реально востребовано, а что лежит мёртвым грузом;
- Дополнительно можно подсмотреть, какие инструменты и интеграции сейчас «в ходу» — многие сервисы и плагины работают именно через OpenRouter.
- Есть бесплатные модели, которые тоже можно попробовать.

Зачем это?

- Любому человеку, кто интересуется темой AI будет полезно, какие технологии стоит рассматривать для пилотов и прототипов, а какие пока «сырые»;
- Можно сравнить отклик разных моделей под свои задачи (от техподдержки до генерации кода) без сложной инфраструктуры;
- Это объективный индикатор «пика популярности» моделей, а не просто маркетинговые пресс-релизы от вендоров.

Например, вы можете зайти в их чат, выбрать из списка Claude 4 Sonnet и Grok 4, задать им одну и ту же задачу по генерации SQL-запроса и сравнить скорость, точность и стиль ответа.
На скриншоте, отображено какие инструменты используют OpenRouter и в каком объеме. Это, кстати, позволяет узнать в том числе и о новых инструментах.

Минусы

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

Также статистика OpenRouter показывает популярность моделей только в рамках своей платформы. Это важный, но не исчерпывающий срез рынка. Крупные компании могут использовать API напрямую от OpenAI, Anthropic или Google, и этот трафик в статистике OpenRouter не отражается. Статистика — это индикатор, но не абсолютная истина. Тем не менее, она показывает тренды.

Мы искали React-разработчика и никого не нашли. Почему вы тоже не можете найти работу.

Недавно искали себе в команду помощника фронтенд-разработчика. На React. Разместили вакансию на hh, и тут началось. Мы просто утонули в откликах от людей без нужного опыта, а те, кто нам подходил, видимо, затерялись в этой массе. В общем, эпопея закончилась ничем, мы никого не взяли.

И это не просто наша частная история, а диагноз всему IT-рынку. Сегодня на Хабре вышла статья Кати Булановой, которая по сути подтвердила мои мысли цифрами.

https://habr.com/ru/articles/941304?utm_source=Telegram&utm_medium=social&utm_campaign=26064343

Если коротко, вот что на самом деле происходит.

1. Рынок кандидата сменился на рынок работодателя.

Время, когда разработчик мог выбирать среди нескольких офферов, прошло. Теперь выбирает компания. Люди это поняли и затаились. Фразы вроде «я выгорел и ушел в никуда» слышны все реже. Все держатся за стабильность, потому что есть реальный шанс уйти и потом вообще не найти работу.

2. Фильтр на входе стал жестче.

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

3. «Вкатуны» создали шум, в котором тонут все.

Рынок завалили выпускники курсов. Народ хочет больших зарплат, но часто нет ни опыта, ни даже базовых знаний. И получается замкнутый круг. Работодатель тратит кучу времени, разбирая сотни пустых резюме. Новичок получает отказ за отказом, потому что он один из тысячи таких же. А толковый, опытный специалист просто теряется в этой лавине откликов. Его резюме может быть 150-м по счету, и до него руки просто не доходят. В итоге плохо всем.

Какой из этого выход?

Опытным ребятам, которые сейчас в поиске, я могу посоветовать одно: хватит быть просто строчкой в общем списке. Общайтесь в сообществах, пишите напрямую тимлидам, показывайте свой код на GitHub. Ваша главная задача сегодня, это пробиться через весь этот информационный шум. Иначе вас просто не увидят.
#Кейсы_КИД

Не каждый разработчик мечтает стать руководителем. И это нормально.

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

Ответ меня не то чтобы удивил, но заставил в очередной раз задуматься. Семён спокойно сказал: «Виталик, мне это не нужно. Я люблю писать код, решать сложные задачи. Мне не нужны вот эти вот созвоны, бюджеты, отчеты и чужие проблемы. Да, зарплата ниже. Зато нервы целее, и я занимаюсь тем, что мне действительно нравится».

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

Это опасное заблуждение.

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

Кодить и управлять людьми — это две разные профессии. Хороший руководитель — это не тот, кто пишет самый изящный код. Это тот, кто:

Берет на себя ответственность. Не ищет виноватых, а ищет решение.

Умеет говорить с людьми. Может и задачу поставить, и конфликт разрулить, и просто услышать человека.

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

Это отдельный, сложный набор навыков. И он никак не связан с умением виртуозно настраивать CI/CD или оптимизировать запросы к базе данных.

Поэтому, прежде чем гнаться за должностью тимлида или начальника отдела, просто честно спросите себя: «А мне это точно надо?». Может, ваш путь — это горизонтальное развитие? Стать незаменимым экспертом в своей области, менторить новичков, заниматься самыми сложными проектами. Это не менее достойный и уважаемый путь.

Интересно, а как у вас в компаниях? Сталкивались с ситуацией, когда отличного спеца «повышали» до плохого менеджера? Или, может, вы сами сделали такой же осознанный выбор, как мой товарищ?

Код ИТ-директора
#Истории_КИД

Нашел интересный сервис энтузиаста-разработчика, который создал сервис для обработки фото. В частности поддерживается создание цветных фотографий из черно-белых, реставрация старых фотоснимков, удаление фона, улучшение качества фотографий (апскейл). Но я бы не приводил этот сервис, если бы не одно НО: сервис абсолютно БЕСПЛАТНЫЙ.

Пользуйтесь: https://photomagics.ru?utm_source=Telegram&utm_medium=social&utm_campaign=26088681

Код ИТ-директора

История про Вову и необжатые коннекторы за которые отвечал я

Иногда одна короткая история из прошлого говорит об ответственности больше, чем толстая книга по управлению. Недавно как раз вспомнил один случай из далекого 2007 года, который отлично иллюстрирует, почему некоторые специалисты навсегда остаются просто исполнителями с которыми никто не хочет работать.

История одного факапа

В тот момент я работал в компании, которая обслуживала клиентов по 1С. Один из них, бюджетная организация, попросил нас вдобавок к основной работе подключить к локальной сети пару компьютеров. Не наш основной профиль, но директор решила, что это не проблема. В штате как раз был админ, назовем его Вова.
У нас в компании тогда даже ходила шутка и директор говорила что однажды его выпорет. Шутка, конечно. Но поводы для неё были совсем не смешные.
И вот мы с Вовой едем к клиенту за 50 км от города. Он тянет сеть, я занимаюсь 1С. Вечером уезжаем, вроде все довольны. Я в его часть работы особо не вникал, и, как оказалось, зря.
На следующей неделе я снова приезжаю к ним. Идем с бухом клиента в другой кабинет и прямо на моих глазах бухгалтер, милая женщина, зацепилась ногами за провода на полу и чуть не упала. Я смотрю, а у них по всему этому кабинету лежат кабели, ничем не закрепленные. Просто скопом лежат на проходе в перемешку.
Спрашиваю: «Что же у вас провода на полу валяются? Так ведь и убиться недолго». А она мне отвечает: «Так это же ваша фирма на той неделе сеть тянула к этому кабинету. Кстати, эти два компьютера так и не подключили к сети, но зато теперь тут везде провода».
И тут меня, что называется, бомбануло. 🔥
Претензию за чужую работу выслушиваю я. Начинаю распутывать этот клубок и вижу апогей картины: на полу лежит пару кабелей, причем размера больше чем нужна, а на конце этих проводов просто голые жилы. Провод даже не обжат. Вроде бы всего два кабеля, но ощущение что их больше.
Вернувшись в офис, я рассказал всё директору. Она в очередной раз пообещала Вове ремень, а меня попросила проконтролировать, чтобы он всё доделал.
Я пошёл к Вове с одним вопросом: «Почему?» Ответ был гениален в своей простоте: «А я коннекторы забыл».
То есть, человек приехал за 50 км, протянул провод, понял, что обжать его нечем, и решил, что лучший выход — это просто всё бросить и молча уехать. Ни слова не сказав ни клиенту, ни мне, ни директору. Он просто сделал вид, что работа выполнена.
Естественно, мы поехали снова. Я, хоть это и не мой профиль, помогал ему всё доделывать, потому что смотреть на эту бухгалтершу было жалко. Под моим контролем он всё закрепил к стене, обжал и все подключил.

Почему это не просто косяк, а диагноз

Таких «Вов» на самом деле полно. Сейчас модно кивать на зумеров, которые могут договориться о выходе на работу и просто не прийти. Но эта история, напомню, из 2007-го. Тогда зумеры только рождались. Так что проблема не в поколении. Проблема в ответственности.
Я до сих пор не понимаю мотивы таких людей.

• Сделать и бросить. Протянуть кабель, закрепить его в кабель-канал и обжать — это не сверхзадача. Это рутина.
• Солгать молчанием. Ну забыл ты коннекторы, бывает. Подойди к клиенту, извинись, скажи: «Мой косяк, не взял инструмент, приеду завтра и всё доделаю за час». Клиент бы понял. Но вместо этого он выбрал трусливое молчание, подставив и меня, и репутацию компании.

Такое поведение — маркер, который проявляется не только в работе. Уверен, что и в личной жизни у таких людей всё строится по тому же принципу: избежать ответственности, сделать вид, что проблемы не существует, и надеяться, что «само рассосётся».

Вывод: «Вова» — это бомба замедленного действия для бизнеса

В конце поста логично встают два вопроса: нужны ли такие «Вовы» компании и что с ними делать?
Мой ответ: категорически не нужны. И дело здесь не в морали, а в чистой математике и управлении рисками.
Давайте просто посчитаем ущерб от забытых коннекторов:

• Две поездки вместо одной (+100 км).
• Моё время, потраченное на выяснение и контроль.
• Его время, потраченное на повторную работу.
• Самое главное — удар по лояльности клиента, который столкнулся с бардаком и неработающим решением.

Финансовые потери это мелочь против главного ущерба от «Вовы». А главный ущерб - это создание непредсказуемости.
Ответственный сотрудник может ошибиться. Он может даже сжечь сервер. Но он тут же придёт и скажет: «Я накосячил. Вот здесь. План действий такой». Его ошибка — это управляемый процесс. Вы знаете о проблеме и можете на неё реагировать.
«Вова» — это неуправляемый хаос. Он молчит. Он создаёт в ваших бизнес-процессах чёрные дыры, о существовании которых вы узнаете, только когда туда свалится клиент или проект. Такой сотрудник — это ходячий баг в вашей системе управления. Вы никогда не знаете, что у него на самом деле сделано, а что «сделано на словах».
Именно поэтому ошибка простительна, а трусливое молчание — нет. Ошибка — это рабочий момент. Молчание — это саботаж, осознанный или нет.
Привычка доводить дело до конца и не подставлять команду это фундамент, без которого любой опыт и знания бесполезны.

А вы встречались с такими «Вовами» и что, на ваш взгляд, страшнее: сделать ошибку и признаться, или молча уйти в закат и никому ничего не сказать?

Автоматическая сборка PDF-документации из Markdown в GitLab CI

Готовили релиз нашего нового решения для 1С по отправке СМС-подтверждений и столкнулись с классической задачей. Документацию мы ведем в Markdown. Это удобно для нас, но не для конечного клиента.

Клиенту нужен привычный PDF. Простой и надежный.

Главный вопрос: как автоматически собирать несколько .md файлов с картинками в один PDF-файл прямо в пайплайне GitLab CI? Особенно когда твои раннеры работают на PowerShell под Windows, как у нас.

Решение нашлось в связке Docker и Pandoc. Вот пошаговый план:

Основа: Берем готовый Docker-образ с Pandoc.
Подготовка: Внутрь контейнера копируем нашу папку docs с Markdown-файлами.
Сборка: Запускаем Pandoc, который конвертирует все файлы в единый PDF.
Выгрузка: Копируем готовый PDF из контейнера и сохраняем его как артефакт в GitLab.
Подход универсален, неважно, где запущен Docker. Вся логика инкапсулирована в контейнере.

Подробно описал как все это настроить в Gitlab CI и выложи ссылки на github 👉 здесь

Получилось неплохо

Про любимый браузер

До сих пор не понимаю людей, которые используют Google Chrome или Edge. Понятно, что это вопрос холивара, какой инструмент лучше или хуже — большой вопрос.
Лично я использую Яндекс Браузер и уже очень давно. Самое главное, что меня подкупило — это кнопка с озвучкой на русском языке в YouTube :)
Часто смотрю зарубежные каналы и мне этого очень не хватало.

Ну круто же!

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

Что есть такого в Chrome, что нужно использовать его? В Яндекс Браузере есть всё что в Chrome, и даже больше. Расширения ставятся такие же как и в Хром, а еще есть нейроредактор, который позволяет быстро править тексты, есть пересказ на каждой странице в браузере, есть возможность использовать Яндекс Музыку прямо в браузере. Просто нажал и тебе всё пересказал браузер кратко или не очень.

Ставьте себе Яндекс Браузер и пользуйтесь.

Две больших коллекции бесплатных SVG-иконок

В мобильном приложении сейчас активно используем библиотеку SVG-иконок Lucide (лицензия ISC License — похожа на MIT):

https://lucide.dev/icons/?utm_source=Telegram&utm_medium=social&utm_campaign=26209753

Можно задать размер, толщину и цвет.

Еще, мне нравится коллекция Heroicons (MIT License):

https://heroicons.com/?utm_source=Telegram&utm_medium=social&utm_campaign=26209753

Она поменьше, но иконки тоже неплохие. Эту коллекцию используем на сайте Софтонит.

Сохраняйте, чтобы не забыть.

Код ИТ-директора

Как проверять качество кода в 1С? Готовая сборка SonarQube для 1С в Docker

Качество кода в 1С — тема вечная и часто недооцененная. Кривой код сложнее поддерживать, в нем чаще возникают ошибки, а ввод нового разработчика в проект превращается в пытку (как и добавление новых фич в таком коде).

Чтобы систематизировать борьбу с техническим долгом, мы у себя в CI/CD давно используем статический анализатор SonarQube Community. Это мощный (и бесплатный) инструмент, который помогает отлавливать ошибки, уязвимости и просто неудачные решения в коде до того, как они нанесут реальный ущерб.

Подготовил для вас инструкцию по быстрой настройке

➡️ https://codeitdir.ru/tools/sonarqube1c/?utm_source=Telegram&utm_medium=social&utm_campaign=26238670

Нейронки конечно могут… Взял ради прикола текст предыдущего поста и добавил в промпт:

Преобразуй этот документ в красивую HTML-страницу с современным дизайном:

[ВСТАВЬ СВОЙ ТЕКСТ/ДОКУМЕНТ]

Требования к дизайну:
- Современный стиль с градиентами и тенями
- Плавные анимации при скролле
- Адаптивный дизайн для мобильных
- Красивая типографика с контрастом
- Интерактивные элементы (hover-эффекты)
- Используй карточки для блоков информации
- Добавь цветовые акценты и иконки

Создай полный HTML файл с встроенным CSS и JavaScript.

Вставил это сначала в бесплатный Qwen, а потом в ChatGPT 5

Получились прям продающие страницы 🙂

Взгляните-ка на скриншот. Вот так выглядит оформление от ChatGPT. Qwen тоже получилось не плохо, ниже скину ссылка для того, чтобы поглядеть.

Что это дает обычному пользователю?

Мы можем красиво и абсолютно бесплатно преобразовать любой скучный текст в красивый HTML-документ, сохранить его потом в PDF и отправлять клиентам. Или прям так отправлять. Таким же образом можно делать:

- Коммерческие предложения
- Презентации
- Портфолио
- Гайды, уроки, инструкции

И все это можно сделать бесплатно в Qwen. В ChatGPT у меня подписка, но думаю и там можно на бесплатном тарифе что-то подобное сделать.

На всякий случай прилагаю оформление в виде архивов с HTML, которые можно скачать и посмотреть:

ChatGPT
Qwen

Я решил убить старую базу знаний на Битрикс с документацией по нашим продуктам. Часть 1

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

Надо зайти и изменить статью? Открываешь админку сайта, заливаешь картинки, добавляешь текст статьи на сайте, и она сразу же отображается для клиентов. Удобненько (как тогда казалось).

Время идет, всё меняется, и вот уже ты видишь проблемы со старым подходом:

- В Битрикс оказывается неудобный встроенный редактор статей. Редактируешь статью, сохраняешь, в админке она выглядит так, а для пользователей верстка едет. Переключаешь в режим HTML, а там левые теги. Приходится их вычищать.
- Понимаешь, что есть проблемы с добавлением и изменением изображений. Нельзя вставлять изображения в статью из буфера обмена. Также изображение добавляется в медиабиблиотеку, а стандартный редактор использует уже изображение оттуда. В целом это работает не очень быстро. Процесс обновления одного скриншота превращается в квест из девяти кругов ада: сделай скриншот, сохрани файл, зайди в админку, открой медиабиблиотеку, загрузи файл, скопируй ссылку, вернись в статью, вставь ссылку… Хочется просто перетащить картинку в редактор, а вместо этого ты тратишь 10 минут на рутину. А если нужно поменять 20 картинок? Это просто воровство времени у команды разработки. Жесть.
- Плохой поиск. Прям очень. Было пару раз, что поиск отваливался в базе знаний после обновления Битрикс, и за мной ходила менеджер по продажам и говорила, как ей показывать какие-то фичи клиентам и отвечать на их вопросы, если она не может ничего найти в базе знаний. А изменить ты особенно ничего не можешь. Не будешь же править Битрикс и искать, в чём косяк. Потом это, конечно, всё восстанавливалось со следующими обновлениями, но осадочек от этого остался.
- Но всё это мелочи по сравнению с главной проблемой, которая меня бесит: документация живёт своей жизнью, отдельно от кода. Разработчик выкатил фикс, а документация осталась старой. В итоге клиент читает одно, а в программе видит другое. Это прямой путь к потере доверия. И именно этот разрыв стал для меня последней каплей.
Я задумал на сайте Софтонит заменить старую документацию и использовать концепцию Docs-as-Code. Что это вообще за концепция?

Всё просто — работаем с документацией так же, как и с исходным кодом программы. Заводим папочку «docs», и все скриншоты и файлы в текстовом формате (обычно это markdown) пишем и изменяем тут же, а потом пушим всё в Git. При пушах срабатывает линия сборки, которая автоматически разместит документацию на нашем сайте. При таком подходе мы получим:

- Версионирование документации. Удобно видеть версии документации.
- Документация соответствует коду, который изменяется, и она обновится тогда, когда мы выпустим релиз. Т.е. документация следует за кодом (но тут всё зависит от того, как вы настроите линию сборки).
- Можно использовать любимые markdown-редакторы. Лично мне нравится редактор Visual Studio Code и плагин для Markdown. Оно умеет и из буфера файлы вставлять в текст, и даже есть свой линтер для формата Markdown (подчеркивает желтым, если ты что-то не так делаешь в оформлении текста).
- Мы отделяем текст документации от оформления этого текста на сайте. Есть куча генераторов статических сайтов, которые потом используют нашу доку, это всё сопрягается вместе, и мы получаем красивые мини-сайты с нашими markdown-файлами. Всё это работает очень быстро и выглядит очень круто. Там и встроенный поиск, и красивые стили, и адаптивность и т.п.
Но это всё теория! 🙂 Легко всё на бумаге, но вот внедрить всё это будет непросто. У меня пока нет готового решения.

Я пока не определился, что использовать в качестве генератора статических сайтов и как организовать сборку для всего нашего ПО. Есть такие инструменты, как Diplodoc, Docusaurus, Hugo, MkDocs или Gatsby, и они часто применяются для таких целей. Но на каком остановиться, пока не ясно.

В общем, начинается эпопея под названием «Убираем старое и ставим новое» 🙂

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

А на чём живёт ваша документация? Тоже страдаете, как мы сейчас, или уже нашли самый лучший инструмент для документации?

PS: Продолжение следует…
PPS: Скриншоты можно посмотреть в оригинале статьи