Комментарии 17
Я не настоящий сварщик, возможно поэтому не совсем понял детали.
Аналитик, технический писатель чем в своих ветках занимаются? Могу предположить, что какждый правит собственный набор Markdown файлов. После merge другим становится видна сразу финальная версия (без черновиков), и это хорошо.
Но откуда тогда берутся конфликты? Разработчик правит файлы, подготовленные аналитиком?
Или аналитик и технический писатель все-таки не только над своими файлами работают, а добавляют комментарии (docstring) непосредственно в код?
Возможная причина конфликта может заключаться в том, что аналитики часто работают параллельно над несколькими историями. Например, в ветке STR0000000000-tema-istorii перед слиянием в dev может возникнуть конфликт, если другая параллельная история была интегрирована раньше.
Аналогичная ситуация может произойти и с другими членами команды при вливании STR0000000000-tema-istorii в dev, например, с разработчиками.
В результате конфликт может возникнуть как в файле аналитика, так и в файле разработчика, что требует совместного решения обеих сторон. Подобные ситуации случаются редко, и у нас разработаны процедуры для их оперативного разрешения как в синхронном, так и в асинхронном режиме.
Удивлен тем что рассматривают аж целых 2 варианта: гугл док и спецификацию как код.
Миновав валом промежуточных вариантов, в том числе все возможные трекинг сервисы - та же жира.
Но раз я этот бред асилил, то напишу развернуто.
"Спецификация" - это сферический конь в вакууме. Она бывает разной и(вы удивитесь) есть валом инструментов для работы с разными видами спецификации.
Начинается все со списка бизнес требований к продукту и любое хранилище данных, включая гул докс - норм. Выбор конкретного решения зависит от стандартов компании, ее размеров, и так далее. Можно ли эту документацию трекать в гите - скорее нет чем да, потому что стейкхолдеры - это бизнес которому все эти гиты, бранчи, мердж реквесты и тд и тп не нужны. А историю изменений трекают все сколько-нибудь популряные сервисы.
Затем из списка требований получается техническое предложение по реализации. Можно ли его трекать в гите и апдейтить вместо с кодом? Скорее да чем нет. Тут уже стейхолдеры технари, нам такое нравится. Но есть технические сложности которые надо порешать: выбор формата написания текста(.docx файлы при мерже нечитабельны) и формат рисования картинок - опять таки решаемо, но немного геморно. Есть ли альтернативы? Валом, начиня с того же гугле докса. Главный минус альтернатив - оторванность от кода. Но как пишут авторитетные дядьки "documentation must be up to date but not too up to date".
После документации пишут код, которsй конечно же все привыкли видеть в гите. Код пишут не просто так, а с привязкой к некоторым "задачам" и очевидным же тайтрекингом. Можно ли трекать "задачи" в гите - можно, но есть валом инструментов в которых их трекать попросту удобней. Включая статистику по ним, в том чсиле построение burndown и прочих других графиков и отчетностей, которые работают из коробки в десятках продуктов. Кто стейхолдеры этих документов - правильно, пм-ы и прочие не технари, которые привыкли работать со своими инструментами, и гит "из коробки" им не посчитает загруженость WBS.
А параллельно с кодом иногда пишут тесты. Включая описание тест кейсов и формирование на их основе тест сетов и потом - трекание запусков этих тест сетов и документирование результатов(включая создание неизбежных багов). Можно ли их трекать в гите? Конечно можно, но насколько это удобно? Наверное не очень, хотя есть варианты. Стейкхолдеры тут очевидно QA, BA, PMs. Которые опять таки не очень дружат с гитом и снова любят всякие статистики которые делаются в 2 клика мыши в любом специализированном сервисе.
Следующий этап документирования - это некий юзер мануал, который опять таки пишут BA, и апдейтят с каждым релизом. Можно ли научить BA писать маркдауном и делать мердж реквесты? Наверное да, но зачем?
В общим идея трекать часть документации как код - интересная и здравая, но надо понимать ограничения этого подхода, включая назначение документов, типичные навыки разных стейхолдеров, наличие сервисов которые решают ряд задач из коробки эффективней чем "мы в одном бранче и доку и код проадейтили".
Спасибо за ваш комментарий. Вы затронули важные моменты, я вижу, что в вашем рассуждении присутствует смешение понятий таск-трекинга (управлением задачами) для разработки и управление изменениями в документации (нашем случае именно спецификации требований).
Управление задачами касаются процесса работы над проектом или продуктом, контроля сроков и распределения ресурсов, это отдельные инструменты нашего SDLC. Управление изменениями в спецификации в свою очередь так же выделенный процесс со своими артефактами и инструментами. Отрадно, что Ваш вывод повторяет посыл статьи, "идея трекать часть документации как код - интересная и здравая".
в вашем рассуждении присутствует смешение понятий таск-трекинга (управлением задачами) для разработки и управление изменениями в документации
отнюдь, я отдельно рассматриваю разные виды проектной документации. Вы же пишете только про «спецификации», даже не обьясняя, что вы под этим термином понимаете.
У нас очень хорошо зашло network rules as a code. В двух словах - раньше, чтобы пробить коннект с одного дата центра на другой (или тем паче в амазон или в какой-то внешний ресурс) нужно было заполнять огромных размеров DOC файл, отправлять его куда-то там и ждать согласования. Теперь просто делается пулл реквест, где в YAML файле пишется source и destination.
Да, для определенных задач git - это прекрасный инструмент. Как раз хотелось этой статьей подсветить, что git можно использовать не только для кода.
гугл докс тоже прекрасный инструмент. Вы вынесли 2 проблемы, которые у вас были в гугл докс и которые вы решили переходом на гит:
Отсутствие версионирования: Трудно было отслеживать изменения и возвращаться к предыдущим версиям спецификаций.
Трудности в совместной работе: Было трудно сообщать о конкретных изменениях в спецификации с течением времени. Процесс ревью спецификаций был муторным и синхронным.
В гугл докс есть версионирование и есть нотификация пользователей об изменении документа - вы решили процессную проблему заменой инструмента и модификацией процесса - хотя с инструментом все и так хорошо.
Спасибо за ваше мнение! Инструменты вроде Google Docs действительно имеют свои плюсы, но подходы к управлению документацией могут сильно различаться в зависимости от задач и процессов. Мы не можем согласиться с тем, что Google Docs полностью удовлетворяет наши потребности в управлении изменениями в спецификациях требований.
Многие из ваших вопросов, скорее всего, можно решить, если подробнее изучить подход docOps (например в сообществе https://t.me/docsascode). Этот метод помогает более эффективно управлять версионированием, совместной работой и прозрачностью изменений. Рекомендую обратить внимание на docOps — возможно, он окажется полезным и для вашего рабочего процесса.
Многие из ваших вопросов, скорее всего, можно решить, если подробнее изучить подход docOps
я всего лишь несколько лет назад настаивал на введение docOps в крупной международной компании. Если коротко, то получив практический опыт, команда решила что усложнение процесса не оправдывает конечного результата.
спасибо! Интересная статья! Многое отозвалось.
Подскажите, зачем техпису отводить отдельную ветку, а не создавать PR-ы с файлами переводов сразу в ветку аналитика?
Не уверена, что правильно поняла вопрос, но попробую ответить. Технический писатель отводится от ветки аналитика (а не от devа) для того, чтобы делать переводы по определенной версии спецификации. Лично я могу в нужных местах спецификации прописать для упрощенного поиска TODO: техпису, для того, чтобы подсветить определенные моменты.
Если про то, почему бы двум людям не работать в одной ветке, то это считается плохой практикой из-за повышенных шансаов начать "толкаться локтями". Также, при необходимости, в своей ветке аналитик может снова инициировать черновую работу (в которой он еще не уверен) и не запутает техписа.
Тут конечно от *-as-a-code только контроль версий гита. Никакой конвергенции кода со спекой очевидно нет, надо её руками делать, поэтому тут скорее "спека в гите"
И вопрос - как будете работать с дивергенцией кода и спеки в гите?
Ревьюер при проверке merge request видит как изменения в коде, так и в спецификации. Он проверяет их на синхронность и соответствие друг другу. Тестировщики также участвуют в этом процессе, чтобы убедиться, что требования из спецификации покрыты тестами и реализованы корректно.
Изменения в коде не могут быть приняты, пока не будет обновлена и проверена соответствующая документация
В будущем можно настроить автоматическое выполнение тестов, которые проверяют корректность связей между документацией и кодом для определенных случаев, но мы пока за это не брались.
Спасибо за статью! Было бы еще интересно посмотреть, как ваши спеки выглядят (то, что аналитик именно пишет), и как в них вливаются переводы от тех писов
Gitlab и Specification-as-Code: спасение от хаоса и кофеиновой зависимости