Можно в пунктах требований указывать такие же айдишники ТЗ, 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 не собрать пользовательскую документацию, как мне кажется. И там, обычно, нет описания зачем мы что-то разрабатываем, какие есть бизнес-ограничения, почему они есть и много чего еще.
Docs as code — это прежде всего про процессы и инструменты, а не про то, откуда берётся текст. Пруф: https://www.writethedocs.org/guide/docs-as-code/ Автогенерация документации из кода – это отдельное независимое направление.
По Markdown в гите можно diff смотреть и ревьюить через MR/PR. А docx — бинарник, с ним ничего не сделаешь, кроме как открыть и вручную сравнивать с docx из другой ветки.
Да, уже поддерживаем Bitbucket, Gitea, Gogs, GitVerse, GitFlic. Как подключить. GitLab self hosted в open source выложен, можно спокойно использовать. Плюс недавно запартнёрились с GitVerse, хорошая и приятная команда у них.
Obsidian с нативной интеграцией с git, с комментариями и мерж реквестами :) Сейчас фокус больше на создание публичной документации для продуктов (обычно делается через SSG, GitBook), но можно и вести собственную вики корпоративную. Доступы можно через GitLab/GitHub регулировать в open source версии или через наш UI в платной.
Понравилась статья, спасибо! Пробовали ли размещаться в awesome lists на GitHub? И размещение на индийских ютуб-каналах было платным?
Мы только сейчас начали заниматься вопросом звёзд на GitHub. Но их уже пассивно набралось 84. Звёзд 10 набрали просто после того, как привели readme.md в порядок на английском и нас начали находить в поиске. Сейчас хотим пробовать awesome lists и работу с блогерами рус/англ.
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 не собрать пользовательскую документацию, как мне кажется. И там, обычно, нет описания зачем мы что-то разрабатываем, какие есть бизнес-ограничения, почему они есть и много чего еще.
Docs as code — это прежде всего про процессы и инструменты, а не про то, откуда берётся текст. Пруф: https://www.writethedocs.org/guide/docs-as-code/
Автогенерация документации из кода – это отдельное независимое направление.
По Markdown в гите можно diff смотреть и ревьюить через MR/PR. А docx — бинарник, с ним ничего не сделаешь, кроме как открыть и вручную сравнивать с docx из другой ветки.
В виде картинки, т.к. хранится в svg. Думали насчёт xml, но тогда нужно будет делать серверный рендеринг, пока решили отложить на потом.
Записал видео для демонстрации, сначала mermaid, потом draw.io.
https://rutube.ru/video/16f45bd2d0cf9354c6219b254065f536/
Да, уже поддерживаем Bitbucket, Gitea, Gogs, GitVerse, GitFlic. Как подключить.
GitLab self hosted в open source выложен, можно спокойно использовать.
Плюс недавно запартнёрились с GitVerse, хорошая и приятная команда у них.
Спасибо!)
Obsidian с нативной интеграцией с git, с комментариями и мерж реквестами :)
Сейчас фокус больше на создание публичной документации для продуктов (обычно делается через SSG, GitBook), но можно и вести собственную вики корпоративную. Доступы можно через GitLab/GitHub регулировать в open source версии или через наш UI в платной.
Понравилась статья, спасибо!
Пробовали ли размещаться в awesome lists на GitHub?
И размещение на индийских ютуб-каналах было платным?
Мы только сейчас начали заниматься вопросом звёзд на GitHub. Но их уже пассивно набралось 84. Звёзд 10 набрали просто после того, как привели readme.md в порядок на английском и нас начали находить в поиске. Сейчас хотим пробовать awesome lists и работу с блогерами рус/англ.