Backward-трассировка требований в Git
Меня зовут Александр Мачулин, я основатель Gramax – open source системы для ведения документации в подходе Docs as Code с визуальным редактором. Сегодня я расскажу вам идею, как вести всю документацию по проекту и весь цикл разработки в одном Git-репозитории и настроить backward-трассировку требований в Git. Интересно, давай!
Docs as Code – Code as Docs – No Docs
Какие главные проблемы технической документации? Во-первых, ее нет, во-вторых, если она есть, то не актуальна. Давайте порассуждаем, как мы можем попытаться упростить себе жизнь при создании документации, а главное увеличить ее актуальность и качество. Существует три класса задач, которые решает техническая документация: 1. Описать наши требования к системе и принятые решения 2. Описать текущее состояние системы 3. Объяснить пользователю, как работать (\разворачивать\эксплуатировать) с системой. Первый тип документации — наши требования к системе. В эпоху LLM, кодогенерации и декларативного подхода к описанию инфраструктуры, мы будем вести требования так, чтобы система, там где это возможно, сама собиралась из них. Поэтому документация первого типа потребует высокого аудита качества. Ревью изменений, совместная работа, ведение версий, с возможностью отката, автоматическая сборка. Все то, что присуще подходу Docs as Code. Второй тип документации — описание текущего состояния системы. Так как мы не хотим разрыва между описанием системы и самой системой, мы будем пытаться генерировать человеко-читаемое описание из кода и конфигурации. Назовем этот подход Code as Docs. Третий тип — различные виды пользовательской документации. Эту форму документации мы постараемся минимизировать, сделав понятным наши интерфейсы и встроив подсказки прямо в процесс работы пользователя с системой. Назовем это подходом No Docs. На этом можно было бы и закончить, но пройдемся подробнее по каждому пункту.
Как мы с ИИ перезапустили документацию Bitrix Framework и сэкономили 400 часов
Привет! Меня зовут Марина Павлова, я технический писатель в отделе документации 1С-Битрикс. В этой статье я расскажу, как мы полностью переделали документацию по Bitrix Framework и как команде из двух человек удалось выпустить доку за 9 месяцев с помощью ИИ.
https://habr.com/ru/companies/bitrix/articles/959134/
#bitrix #framework #документация #bitrix_программирование #documentation #docsascode #docs_as_code #docs #ии #нейросети
Автоматизация документации: MkDocs Material + GitLab CI/CD + Битрикс
Всем привет! В процессе обновления инфраструктуры сопровождения наших программных решений мы получили интересный опыт, которым хотим поделиться. Эта статья не просто пошаговая инструкция, а практический разбор того, как мы выстроили процесс подготовки технической документации на основе MkDocs Material , автоматизировали его через GitLab CI/CD и встроили полученный результат в сайт на Битрикс. Наш опыт окажется полезным тем, кто хочет навести порядок в документации и сделать её частью полноценного dev-процесса.
https://habr.com/ru/articles/925476/
#mkdocs #mkdocs_material #продуктовая_документация #docs_as_code
От Docs as Code к Everything as Code: как Gramax меняет работу с документацией
Привет, Хабр! Меня зовут Катя, я лидирую Gramax , open-source платформу для управления технической документацией. Однажды мы с коллегами утонули в хаосе рабочих документов: без версий, без согласований, без истории принятых решений. Это подтолкнуло нас к созданию Gramax — инструмента, который интегрирует документацию в процесс разработки, делая его прозрачным и управляемым. В этой статье расскажу, как Gramax помогает на каждом этапе разработки ПО. Как перейти к документированию в подходе Docs as Code и шагнуть дальше — к Everything as Code. Интересно, давай!
https://habr.com/ru/articles/910716/
#сезон_open_source #docs_as_code #everything_as_code #adr #аналитика #анализ_и_проектирование_систем #документирование #документация_проекта #документация_на_по
Gitlab и Specification-as-Code: Спасение от хаоса и кофеиновой зависимости
Для компании SimpleOne управление спецификациями требований было настоящей головной болью, требующей унификации подходов и учета потребностей разных команд. Мы стояли перед выбором: сделать свое решение для управления требованиями и сбора спецификаций или попробовать уже существующие практики. Концепция DocOps привлекла внимание тем, что помогает стандартизировать инструменты и навести порядок в хранении артефактов. В этой статье мы расскажем, как внедрили подход на основе docs as code, какие преимущества получили и какие трудности преодолели на пути.
https://habr.com/ru/companies/simpleone/articles/844080/
#аналитика #спецификация #управление_проектами #управление_требованиями #системный_анализ #бизнес_анализ #docsascode #git #markdown #docs_as_code
Diagrams (or drawings) are the language of engineering, whether it be civil, mechanical or software. Try to express, convey and document ideas, thoughts and designs primarily using diagrams. Text should be structured, and version controlled. #docs_as_code
