Далеко не все участники создания программного продукта — программисты. Бизнес-аналитики, технические писатели и менеджеры привыкли к визуальным редакторам вроде Confluence.
Подход DOC-AS-CODE и переход на ИИ-инструменты требуют хранения документации в Git-репозиториях в формате Markdown. Однако требовать от аналитика писать спецификации в VS Code или Notepad++ — прямой путь к саботажу процесса.
Здесь на помощь приходит Obsidian. Он позволяет скрыть от нетехнических пользователей сложность Git, предлагая удобный интерфейс для работы с текстовыми файлами (`.md`). Полностью избежать «программистских штучек» не получится, но их можно свести к пяти простым шагам.
1. Подготовка рабочего места Клонируем репозиторий с документацией на локальную машину:
«`python
git clone https://your.repo.git
«`
2. Изоляция изменений Создаем отдельную ветку, чтобы ваши файлы не конфликтовали с основной документацией:
«`python
git checkout -b имя_ветки (например, ticket-123-update-sdd или ivanov-ai-docs)
«`
Теперь все ваши изменения будут фиксироваться только в этой ветке.
3. Работа в Obsidian Открываем в Obsidian папку с документацией внутри клонированного репозитория.
Интерфейс программы выглядит примерно так:
В таком виде работать с текстом, заголовками и таблицами Markdown гораздо приятнее, чем в «голом» блокноте. Obsidian мгновенно отображает изменения в файлах на диске.
4. Подготовка к сохранению Когда спецификация готова, возвращаемся в терминал. Добавляем созданные или измененные файлы в будущий коммит:
«`python
git add .
# или выберите конкретные файлы:
# git add path/to/your/spec.md
«`
Фиксируем изменения:
«`python
git commit -m «feat(sdd): обновил спецификацию по интеграции с ИИ-агентом»
«`
5. Отправка в репозиторий Загружаем локальную работу на сервер:
«`python
git push -u origin имя_ветки
«`
_Примечание: флаг `-u` нужно использовать только при первой отправке этой ветки. В следующие разы достаточно будет команды `git push`._
После этого останется только создать Merge Request (или Pull Request) в интерфейсе вашего Git-репозитория, чтобы влить изменения в основную ветку.
В чем преимущество этого лайфхака:
— Для нетехнических специалистов: знакомый интерфейс текстового редактора вместо пугающей IDE.
— Для команды разработки: чистый Markdown, который легко парсится ИИ-агентами, версионируется в Git и не требует ручного переноса текста из визуальных редакторов.
В итоге получаем идеальный баланс: минимум кода в консоли для пользователя и максимум порядка в документации для разработчиков.