Comments 14
Интересный подход, спасибо за описание.
Возникло несколько вопросов:
Кто, на ваш взгляд, должен быть ответственным за такую документацию в Git?
Как считаете, каким образом можно контролировать необходимый и достаточный объем описаний? Кто, на ваш взгляд, должен это делать? Например, в процессе разработки требования сделали, но забыли указать в Git необходимую ссылку.
Если какую-то фичу отменили/отключили, подход к сохранению изменений остается аналогичным? Или есть какие-то нюансы? Мне кажется нюансов быть не должно, но вдруг что-то не понял. Было бы интересно ваше мнение.
Спасибо за вопросы!
Если вы о пользовательской документации, то это зависит от компании и её процессов. За документацию может отвечать разработчик, аналитик или технический писатель – и это может так и оставаться. Основной смысл подхода – в том, чтобы документация жила и развивалась вместе с проектом. Важно, чтобы разработчики писали черновик документации и обновляли его по ходу разработки, чтобы из этого черновика в дальнейшем можно было сделать красивую пользовательскую документацию с помощью коллег.
Если речь про PRD/RFC, то ответственный – автор. Он может принимать правки по ходу разработки напрямую или через Merge Request.У нас это работает через ревью. Разработчик пишет RFC, его проверяют продакт, тимлид, иногда CTO. Если чего-то не хватает, то даём обратную связь на звонке или в комментариях.
Вопрос со ссылками решается дисциплиной, автоматическими проверками и случаями, когда кто-то не нашёл нужные изменения и пришлось вручную добавить тег, чтобы в будущем это не повторялось по конкретно этому кейсу :)Да, подход аналогичный. На отключение должны же быть требования, потом задача, потом реализации в коде и корректировка документации. Мы отслеживаем изменения, как добавление, так и удаление.
В конфиге написано timeout=30s. Раньше было timeout=5s. Кто-то увеличил значение в три раза. Почему? Git blame показывает, кто это сделал. А вот причина – утеряна.
Надо в commit message писать «зачем поменялось», а не «что поменялось» (это и так по диффу видно).
Все что вы описываете есть в GitLab / Azure / etc (задачи прикреплять к коммитам), надо создать один документ с описанием процесса работы в команде и все ему должны следовать. Если команда не способна на это, то и ваша идеея ни чем не поможет.
Если документ говорит о том, что необходимо актуализировать информацию в трех системах – вики, таск-трекер, система документирования, то дисциплиной тут никак не решается. Обычно, решают увеличением ролей в команде – аналитики, тех. писатели и т.д., которые отвечают за обновление других систем. И всё равно информация безнадёжно устаревает.
Вики, таск-рекер и большинство систем документирования не поддерживают контроль изменений, чтобы можно было отследить изменение контента в рамках такой-то задачи.
То, что я описал, можно делать и в Git, без GitLab / Azure / etc. :)
Если рассматривать GitLab и Azure как комбайн инструментов. То конкретно вики в GitLab и Azure не поддерживают комментарии фрагментов текста, что уже усложняет работу над PRD и RFC.
Ваше понятие "Single Source of Truth" мне не совсем понятно :). Зачем создавать 100500 разных *.md файлов (по замороченному процессу, тэги, т.д.) вместо того чтобы обновить один документ где описана вся система / требования ? Так трудно при обзоре слияния в ветку develop проверить и документацию ?
Вики, таск-рекер и большинство систем документирования не поддерживают контроль изменений, чтобы можно было отследить изменение контента в рамках такой-то задачи.
Решается элементарно: в описании кода добавляется тэг \req us-127. В git смотрите когда появилось изменение, там будет и номер требования.
К тому же, для кода важны только SW requirements. В описание SW requirementa должна быть ссылка на System Requirement и т.д. Не надо держать все ссылки в одном коммите, так их легче потерять, все и сразу :) (к примеру после squash).
Возможно я не уловил сути вашей идеи.
Как может один документ описывать всю систему? В нём будет 300+ страниц и с ним будет весьма сложно работать. Я описывал что под каждый RFC, PRD нужен свой документ. На Хабре есть ещё одна статья про требования, где каждое требование предлагается в отдельный .md-файл вынести, но это перебор, как по мне.
Процесс замороченный, поэтому он ещё на стадии обдумывания, а не в проде :)
\req us-127 это вы для кода добавите такой тэг и трассировку. А другие проектные документы у вас продолжат бесконтрольно изменятся или не изменяться. Для этого и придумал вообще трассировку, разве нет? Чтобы отслеживать изменения от требований до кода, тестов и документации.
Да, squash может навредить. Это ограничение.
Я обдумывал эту идею ещё. Думаю, для начала попробуем перенести всю проектную документацию в один репозиторий. Потом объединить этот репозиторий с кодом. Тогда у нас вся информация по проекту будет в одном репозитории. Никаких вики, гугл доков и прочего. Потом уже думать над трассировкой и следующими шагами.
В нём будет 300+ страниц и с ним будет весьма сложно работать.
Раз проект большой, то и документации много. Сложные проекты надоиразбивать на более мелкие и понятные под-проекты.
А другие проектные документы у вас продолжат бесконтрольно изменятся или не изменяться.
Требования могут менятся, но если вы переписываете us-127 в каждом релизе то это полный угар :) и лучше бы вам нанять профессионального системного инжинера :). В проектах, где я учавствовал, при каждом изменении существующего требования создавалось новое требование с новым номером (скажем us-721) и помечалось для последующих релизов (требование us-127 становилось недействительным, но оставалось навсегда в документе). Если мне надо было посмотреть как система работала в релизе Х, она выдавала мне все требования (включая us-127). Для релиза Х+1, система контроля требований выдавала тоже самое, но вместо us-127 выдавала us-721. Также можно было посмотреть что изменилось между релизами (тогда система выдовала что появилось us-721 а us-127 более недействительна). Ничего не надо переписывать и плодить хаос.
Я тут немного поздно, но вопрос задам.
Были ли мысли по поводу реализации ну назовем это forward-трассировкой требований?
Т.е. когда у вас есть вот эти все линки "что на основании чего сделано" -- система должна уметь капать на мозги в духе
"Вот этот пункт в ТЗ был поставлен на основании требований более высокого уровня (ссылка на параграфы внутри тех самых требований). Они изменились. Посмотрите, поправьте и закоммите новый вариант."
А далее по индукции вплоть до кода.
Можно в пунктах требований указывать такие же айдишники ТЗ, RFC или задач на разработку. Можно будет увидеть, какие пункты из требований не реализованы. Но из строчки кода сделать трассировку до конкретного требования не получится. И надо ли оно? Такую трассировку весьма дорого поддерживать.
Но из строчки кода сделать трассировку до конкретного требования не получится.
Не в эту сторону. Из параграфа требований в другой параграф, более подробных требований и дальше до строчки кода.
И надо ли оно? Такую трассировку весьма дорого поддерживать.
Она так и так есть, только ручная. Регулятор что-то изменил своих документах - и начинается поиск по всем документам, что поправить надо. Сначала во внутренних требованиях и далее по цепочке - до кода. Причем в ручном варианте знание 'это требование регулятора мы вот сюда вписали' -- оно просто в головах и имеет свойство забываться/теряться с уходом людей.
Интересный подход, спасибо! А где можно почитать подробнее про базовые стандарты описания процессов - то, что вы упоминаете как PRD и RFC? У меня по привычке RFC ассоциируются с длинными спеками к веб-протоколам. А ведь есть ещё ADR, он как-то участвует в процессах у вас?
По ходу знакомства с Gramax не совсем понятно, как описанная Вами структура переносится туда.
Во-первых, на Gramax позиционируется как генератор сайтов пользовательской документации. А у вас тут описана структура для внутренних документов, которые не обязательно публиковать.
Во-вторых, Gramax ведь перелопачивает файловую структуру с md-файлами под оглавление сайта со страницами на разных уровнях. Кто-то по привычке добавит просто файлы в папках и подгрузит напрямую в Git-репозитрорий, к которому подключен Gramax - и что тогда? Утрачивается привычная структура из папок-разделов и файлов-документов. А это в свою очередь создает несовместимость с другими markdown-редакторами. Вот я открыл репу Gramax в Obsidian, и получил кучу внутренних технических файлов с непонятными заголовками и свойствами:
Получается как бы окрытый формат, но по факту это vendor lock-in, т.к. правильно работать можно только через редактор Gramax (пускай он и опенсорсный)?
Так что я пока попробую организовать техническую документацию в md-файлах по старинке...
Про базовые подходы Claude или ChatGPT лучше всех знают. Я знаю, что так работает в крупных американских компаний из опыта изучения темы, но называться может немного по разному порой. RFC это и есть ADR, как по мне. Я по тексту прикладывал ссылки на примеры: вот пример на RFC Flutter, там и юзкейсы описаны, и DETAILED DESIGN/DISCUSSION.
Вы правильно считали текущее позиционирование с сайта 😅 Но, вообще, Gramax – это достаточно продвинутый текстовый редактор в первую очередь. Может пока не такой продвинутый, как Обсидиан, но мы к этому идём.
Как и любой продукт, Gramax имеет свою логику и ограничения. Её надо изучить, прежде чем переходить в исходники. Насчёт совместимости:
У нас в настройках каталога можно включить GitHub Flavored Markdown. Но тогда в интерфейсе будет отключен ряд функций, которые GFM не поддерживает.
Obsidian тоже несовместим с другими продуктами. Obsidian славится не тем, что его используют из коробки as is, а большим количеством плагинов от сообщества. Практически любой плагин, которые расширяет возможности Obsidian, обрывает совместимость с другими продуктами.
Вам спасибо за вопросы и комментарии!
Backward-трассировка требований в Git