Про базовые подходы Claude или ChatGPT лучше всех знают. Я знаю, что так работает в крупных американских компаний из опыта изучения темы, но называться может немного по разному порой. RFC это и есть ADR, как по мне. Я по тексту прикладывал ссылки на примеры: вот пример на RFC Flutter, там и юзкейсы описаны, и DETAILED DESIGN/DISCUSSION.
Вы правильно считали текущее позиционирование с сайта 😅 Но, вообще, Gramax – это достаточно продвинутый текстовый редактор в первую очередь. Может пока не такой продвинутый, как Обсидиан, но мы к этому идём.
Как и любой продукт, Gramax имеет свою логику и ограничения. Её надо изучить, прежде чем переходить в исходники. Насчёт совместимости:
У нас в настройках каталога можно включить GitHub Flavored Markdown. Но тогда в интерфейсе будет отключен ряд функций, которые GFM не поддерживает.
Obsidian тоже несовместим с другими продуктами. Obsidian славится не тем, что его используют из коробки as is, а большим количеством плагинов от сообщества. Практически любой плагин, которые расширяет возможности Obsidian, обрывает совместимость с другими продуктами.
У нас в Gramax всё очень бирюзовое и свободное, но когда не фиксируем требования, то получаем переделки. Потому что каждый человек по своему понимает информацию на встречах. Если всё записать и, в идеале, прототип приложить из ЛЛМа, то риск переделки стремится к нулю.
Сначала было ограничение, что Enterprise версия была в одном репозитории с Open Source версией. От этого ушли. Потом было ещё какое-то ограничение, точно не помню какое. Да и просто много других задач, до этой не добираемся.
Но думаю, что в скором времени полностью переедем, чтобы закрыть вопрос. Вся разработка будет в GitHub с пулл реквестами, комментариями и настоящим docs as code.
В аджайле тоже надо уметь писать требования. Кто сказал, что не надо? Аджайл он про быстрое получение обратной связи. Написали требования на MVP продукта или фичи, разработали, пощупали как работает, написали новые требования и так далее.
Можно в пунктах требований указывать такие же айдишники ТЗ, RFC или задач на разработку. Можно будет увидеть, какие пункты из требований не реализованы. Но из строчки кода сделать трассировку до конкретного требования не получится. И надо ли оно? Такую трассировку весьма дорого поддерживать.
Как может один документ описывать всю систему? В нём будет 300+ страниц и с ним будет весьма сложно работать. Я описывал что под каждый RFC, PRD нужен свой документ. На Хабре есть ещё одна статья про требования, где каждое требование предлагается в отдельный .md-файл вынести, но это перебор, как по мне.
Процесс замороченный, поэтому он ещё на стадии обдумывания, а не в проде :)
\req us-127 это вы для кода добавите такой тэг и трассировку. А другие проектные документы у вас продолжат бесконтрольно изменятся или не изменяться. Для этого и придумал вообще трассировку, разве нет? Чтобы отслеживать изменения от требований до кода, тестов и документации.
Да, squash может навредить. Это ограничение.
Я обдумывал эту идею ещё. Думаю, для начала попробуем перенести всю проектную документацию в один репозиторий. Потом объединить этот репозиторий с кодом. Тогда у нас вся информация по проекту будет в одном репозитории. Никаких вики, гугл доков и прочего. Потом уже думать над трассировкой и следующими шагами.
Если документ говорит о том, что необходимо актуализировать информацию в трех системах – вики, таск-трекер, система документирования, то дисциплиной тут никак не решается. Обычно, решают увеличением ролей в команде – аналитики, тех. писатели и т.д., которые отвечают за обновление других систем. И всё равно информация безнадёжно устаревает.
Вики, таск-рекер и большинство систем документирования не поддерживают контроль изменений, чтобы можно было отследить изменение контента в рамках такой-то задачи.
То, что я описал, можно делать и в Git, без GitLab / Azure / etc. :) Если рассматривать GitLab и Azure как комбайн инструментов. То конкретно вики в GitLab и Azure не поддерживают комментарии фрагментов текста, что уже усложняет работу над PRD и RFC.
Если вы о пользовательской документации, то это зависит от компании и её процессов. За документацию может отвечать разработчик, аналитик или технический писатель – и это может так и оставаться. Основной смысл подхода – в том, чтобы документация жила и развивалась вместе с проектом. Важно, чтобы разработчики писали черновик документации и обновляли его по ходу разработки, чтобы из этого черновика в дальнейшем можно было сделать красивую пользовательскую документацию с помощью коллег. Если речь про PRD/RFC, то ответственный – автор. Он может принимать правки по ходу разработки напрямую или через Merge Request.
У нас это работает через ревью. Разработчик пишет RFC, его проверяют продакт, тимлид, иногда CTO. Если чего-то не хватает, то даём обратную связь на звонке или в комментариях. Вопрос со ссылками решается дисциплиной, автоматическими проверками и случаями, когда кто-то не нашёл нужные изменения и пришлось вручную добавить тег, чтобы в будущем это не повторялось по конкретно этому кейсу :)
Да, подход аналогичный. На отключение должны же быть требования, потом задача, потом реализации в коде и корректировка документации. Мы отслеживаем изменения, как добавление, так и удаление.
Специалистом по CAD не являюсь, но вроде файлы .sch хранятся в xml. А это уже открытый формат, независимый от приложения. Аналогично с .xlsx – это набор xml в zip архиве. Работать с исходником в данном случае можно, но неудобно, но и в Markdown не всё идеально.
Смотря о каком маркдауне речь. Основа – это CommonMark. Всё остальное – вариации. В CommonMark не так много элементов и даже нет таблиц, про которые вы говорите :) Пруф: https://commonmark.org/help/
Грамакс нативно поддерживает GitHub Flavored Markdown. Можно писать только на GFM через визуальный редактор. Но эта вариация также весьма ограничена и если нужно больше, то можно использовать вариацию маркдауна от Грамакс или Яндекс.
Тоже as code в виде mermaid диаграмм) Была интеграция со structurizr. Но мы пока убрали её из интерфейса, т.к. для него сервер нужен и ещё какие-то проблемы были. В будущем можем добавить.
Из комментариев к коду или readme не собрать пользовательскую документацию, как мне кажется. И там, обычно, нет описания зачем мы что-то разрабатываем, какие есть бизнес-ограничения, почему они есть и много чего еще.
Про базовые подходы Claude или ChatGPT лучше всех знают. Я знаю, что так работает в крупных американских компаний из опыта изучения темы, но называться может немного по разному порой. RFC это и есть ADR, как по мне. Я по тексту прикладывал ссылки на примеры: вот пример на RFC Flutter, там и юзкейсы описаны, и DETAILED DESIGN/DISCUSSION.
Вы правильно считали текущее позиционирование с сайта 😅 Но, вообще, Gramax – это достаточно продвинутый текстовый редактор в первую очередь. Может пока не такой продвинутый, как Обсидиан, но мы к этому идём.
Как и любой продукт, Gramax имеет свою логику и ограничения. Её надо изучить, прежде чем переходить в исходники. Насчёт совместимости:
У нас в настройках каталога можно включить GitHub Flavored Markdown. Но тогда в интерфейсе будет отключен ряд функций, которые GFM не поддерживает.
Obsidian тоже несовместим с другими продуктами. Obsidian славится не тем, что его используют из коробки as is, а большим количеством плагинов от сообщества. Практически любой плагин, которые расширяет возможности Obsidian, обрывает совместимость с другими продуктами.
Вам спасибо за вопросы и комментарии!
У нас в Gramax всё очень бирюзовое и свободное, но когда не фиксируем требования, то получаем переделки. Потому что каждый человек по своему понимает информацию на встречах. Если всё записать и, в идеале, прототип приложить из ЛЛМа, то риск переделки стремится к нулю.
Сначала было ограничение, что Enterprise версия была в одном репозитории с Open Source версией. От этого ушли. Потом было ещё какое-то ограничение, точно не помню какое. Да и просто много других задач, до этой не добираемся.
Но думаю, что в скором времени полностью переедем, чтобы закрыть вопрос. Вся разработка будет в GitHub с пулл реквестами, комментариями и настоящим docs as code.
В аджайле тоже надо уметь писать требования. Кто сказал, что не надо?
Аджайл он про быстрое получение обратной связи. Написали требования на MVP продукта или фичи, разработали, пощупали как работает, написали новые требования и так далее.
В локальном GitBook не будет визуального редактора, комментариев и множества других функций, которые есть как в облачном GitBook, так и в Gramax.
В репозитории 30 коммитов, т.к. мы пока не переехали из локального GitLab в GitHub. Каждый месяц публикуем новый релиз в GitHub одним коммитом.
Gramax – это только On-premise и Local-first
Выходит пользователю показываем самую последнюю версию и даем ему возможность восстановить нужную из истории?
Речь о Notion. В нём у пользователей есть одинаковые права на блок текста в статье.
Можно в пунктах требований указывать такие же айдишники ТЗ, RFC или задач на разработку. Можно будет увидеть, какие пункты из требований не реализованы. Но из строчки кода сделать трассировку до конкретного требования не получится. И надо ли оно? Такую трассировку весьма дорого поддерживать.
Как может один документ описывать всю систему? В нём будет 300+ страниц и с ним будет весьма сложно работать. Я описывал что под каждый RFC, PRD нужен свой документ. На Хабре есть ещё одна статья про требования, где каждое требование предлагается в отдельный .md-файл вынести, но это перебор, как по мне.
Процесс замороченный, поэтому он ещё на стадии обдумывания, а не в проде :)
\req us-127 это вы для кода добавите такой тэг и трассировку. А другие проектные документы у вас продолжат бесконтрольно изменятся или не изменяться. Для этого и придумал вообще трассировку, разве нет? Чтобы отслеживать изменения от требований до кода, тестов и документации.
Да, squash может навредить. Это ограничение.
Я обдумывал эту идею ещё. Думаю, для начала попробуем перенести всю проектную документацию в один репозиторий. Потом объединить этот репозиторий с кодом. Тогда у нас вся информация по проекту будет в одном репозитории. Никаких вики, гугл доков и прочего. Потом уже думать над трассировкой и следующими шагами.
Если документ говорит о том, что необходимо актуализировать информацию в трех системах – вики, таск-трекер, система документирования, то дисциплиной тут никак не решается. Обычно, решают увеличением ролей в команде – аналитики, тех. писатели и т.д., которые отвечают за обновление других систем. И всё равно информация безнадёжно устаревает.
Вики, таск-рекер и большинство систем документирования не поддерживают контроль изменений, чтобы можно было отследить изменение контента в рамках такой-то задачи.
То, что я описал, можно делать и в Git, без GitLab / Azure / etc. :)
Если рассматривать GitLab и Azure как комбайн инструментов. То конкретно вики в GitLab и Azure не поддерживают комментарии фрагментов текста, что уже усложняет работу над PRD и RFC.
В этом и смысл статьи.
Спасибо за вопросы!
Если вы о пользовательской документации, то это зависит от компании и её процессов. За документацию может отвечать разработчик, аналитик или технический писатель – и это может так и оставаться. Основной смысл подхода – в том, чтобы документация жила и развивалась вместе с проектом. Важно, чтобы разработчики писали черновик документации и обновляли его по ходу разработки, чтобы из этого черновика в дальнейшем можно было сделать красивую пользовательскую документацию с помощью коллег.
Если речь про PRD/RFC, то ответственный – автор. Он может принимать правки по ходу разработки напрямую или через Merge Request.
У нас это работает через ревью. Разработчик пишет RFC, его проверяют продакт, тимлид, иногда CTO. Если чего-то не хватает, то даём обратную связь на звонке или в комментариях.
Вопрос со ссылками решается дисциплиной, автоматическими проверками и случаями, когда кто-то не нашёл нужные изменения и пришлось вручную добавить тег, чтобы в будущем это не повторялось по конкретно этому кейсу :)
Да, подход аналогичный. На отключение должны же быть требования, потом задача, потом реализации в коде и корректировка документации. Мы отслеживаем изменения, как добавление, так и удаление.
По нему diff не посмотреть в git. В этом смысл
Специалистом по CAD не являюсь, но вроде файлы .sch хранятся в xml. А это уже открытый формат, независимый от приложения. Аналогично с .xlsx – это набор xml в zip архиве. Работать с исходником в данном случае можно, но неудобно, но и в Markdown не всё идеально.
На следующей неделе добавим шаблоны для docx. Через 1-2 месяца шаблоны для PDF.
Грамакс по таким же причинам появился :) Но потом пришли бизнес-пользователи и попросили интерфейс, интеграции и много чего ещё :)
Смотря о каком маркдауне речь. Основа – это CommonMark. Всё остальное – вариации. В CommonMark не так много элементов и даже нет таблиц, про которые вы говорите :) Пруф: https://commonmark.org/help/
Грамакс нативно поддерживает GitHub Flavored Markdown. Можно писать только на GFM через визуальный редактор.
Но эта вариация также весьма ограничена и если нужно больше, то можно использовать вариацию маркдауна от Грамакс или Яндекс.
Тоже as code в виде mermaid диаграмм)
Была интеграция со structurizr. Но мы пока убрали её из интерфейса, т.к. для него сервер нужен и ещё какие-то проблемы были. В будущем можем добавить.
Из комментариев к коду или readme не собрать пользовательскую документацию, как мне кажется. И там, обычно, нет описания зачем мы что-то разрабатываем, какие есть бизнес-ограничения, почему они есть и много чего еще.