Комментарии 9
Спасибо, познавательно.
А как быть с ГОCТами, регламентирующими ТД?
Мы рассматривали другой вариант: сделать базовые (элементарные) "юниты" (т.е. фактически подпункты существующей документации). А из этих элементов собирать доки по заранее заданным структурам (РП, РА и т.п.). Это для формального соответствия требованиям. А для пользователей вообще зачем доки? В пределе юниты должны собираться ИИ под конкретный запрос, нет?
Help&Manual давно позволяет выгружать документацию в HTML плюс ядро браузера с возможностью поиска. И, напомню, позволяет включать в док произвольный набор ТОС. Т.е. идея примерно эта же, только без ИИ.
Спасибо за вопросы!
Задача нашей команды — делать практические материалы для разработчиков, а не документацию по ГОСТам. Поэтому мы фокусировались на том, чтобы подготовить понятную и полную документацию.
Что касается юнитов, наша документация работает на платформе Diplodoc и у нее есть возможность переиспользовать блоки информации через include. Мы иногда ей пользуемся, но в приоритете сохранить простоту внесения правок сообществом.
Выбор платформы был обусловлен тем, что к моменту старта проекта, у нас уже была документация на платформе Diplodoc (REST API), процессы были отлажены и нам хотелось поддержать единый стиль
Проще говоря, внутренний заказчик не тробовал по ГОСТу. При закрытии контрактов это невозможно.
Упор не на платформе, а на роли и методах ИИ. Из юнитов можно создавать любой док (или выдачу клиенту). А вы говорите все же о готовых доках, но по бизнес-процессам. Это хорошее дело, но если их много, не всегда реальное.
Подход по юнитам потенциально более гибкий, чем доки. А возможность редактирования любого из них в БД - вообще не вопрос
Интересный кейс. Особенно в части распределения задач между разными ИИ. Но остаётся вопрос: насколько надолго сохраняется точность таких материалов без постоянного участия разработчиков? Всё-таки документация это «живая материя», и автоматизация тут палка о двух концах. Впрочем, подход к структурированию информации сильный, тут не поспоришь.
Да, мы понимаем, что документация устаревает без внимания :)
Поэтому мы следим за обновлениями продукта и сразу обращаемся к разработчикам, чтобы актуализировать материалы. ИИ помогает и здесь — он быстро готовит черновик правок по новому коду, а разработчику остается только проверить. Это экономит много времени.
И конечно, мы очень надеемся на сообщество! Если заметите что-то устаревшее — пишите в ишьюсах или комментариях.
Хорошо что этим занялись. Если честно прошлое старое оформление доки отталкивало от изучения фреймворка, когда интересовался.
Важно не оформление, а контент, а его как не было, так и не стало, потому что тупо механически переписали LLM-кой. Ну и какая в том ценость добавилась? Разобраться, понять, соотнестись как было невозможно так и стало невозможно, но стало "красиво". А документация по API это вообще капец, просто перечисление деклараций функций и параметров, без какой либо сущностной информации, что это за пареметры и что за функции. Полная профанация.
Спасибо. А что за движок сайта документации вы используете? Вы ведь его поменяли полностью тоже?
Как мы с ИИ перезапустили документацию Bitrix Framework и сэкономили 400 часов