Аналогия со строительством моста не понятна. Процессы строительства больше перекликаются с процессом разработки, а не с процессом документирования по факту. С этой точки зрения, вы не строите мост, а восстанавливаете проектную документацию на этот мост после пожара в архиве. Берёте инженера с линейкой, и ходите и всё измеряете. Это больше похоже к.м.к.
В остальном, не понятна цель статьи. Запрос в гугле " кто такой техпис" даст примерно такую же информацию... Ощущение, что хотелось что-то написать и это была единственная тема, через которую можно упоминуть свой ТГ канал...
Ну так вы где вырасли? В тиньке??? Там замкнутая экосистема с весёлым матерком и сомнительными культурными ценностями. Зато расти там можно хоть каждые полгода. И это весь ваш IT опыт? Вы там на айтишников насмотрелись?
Я честно попробовал, но даже по инструкции ничего не получилось.
В статье нет примера результата. Оценить качество документации, которую подготавливает инструмент не получилось.
Формат docx широко распространён в узком кругу опрошенных. Хранить доку в docx это лет 15-20 назад было базой. Сейчас - кто во что горазд. Я например, продвигаю doc as code и пишу на markdown. Может имеет смысл присмотреться к другим форматам...
Вообще, openApi и swagger вполне достаточны для документирования. Примеры есть, подёргать можно. В дополнительном описании эндпоинтов может быть описана системная логика. Но вы такое описание из свагера не вытащите, это не возможно. Тогда встаёт вопрос: кто потребитель вашей документации и для чего она вообще нужна?
В развитых проектах, в отличии от "наколеночной разработки", сначала готовится документация, а потом пишется код. И опять таки встаёт вопрос: кто потребитель вашего инструмента, для кого вы его хотите сделать?
Ну и конкуренция с ИИ. Сейчас модели вполне сносно готовят документацию по эндпоинтам проходясь по коду и вытаскивая всю подноготную из системной логики.
Возможно, есть процессы, в которых данный инструмент будет полезен. Тогда, для продолжения работы, необходимо понимать, что это за процессы, как этот инструмент будет встроен в процесс и какие артефакты будет готовить и как будет их обновлять. Определится с тем, кто является потребителем самого инструмента и кто является потребителем результата его работы. И спросить не у всего сообщества (слишком широкий охват и большой процент нецелевой аудитории) а именно тех, для кого этот инструмент будет полезен.
Я это к тому, что каждый артефакт документации имеет свой жизненный цикл. И если есть программа, генерирующая артефакт, то должна быть в программе поддержка этого жизненного цикла.
Если вы эти артефакты куда-то выкладываете, то как вы их потом обновляете? Как их обновляют другие аналитики? И как эти артефакты упрощают дальнейшую разработку и тестирование? Просто, если вы создали инструмент, который генерит всю ту-же табличку в конфе с маппингом, то чере 5-6 итераций правок станет понятно, что проще её обновлять в самой конфе, без дополнительных инструментов. Потому что будет вечный процесс: подгрузи актуальную версию, поправь её, выгрузи обратно. И если это правка в одном поле, то никто замарачиваться не будет... С json, по большому счёту, тоже самое...
Соответственно и вопросы эти сводятся к одному: Вы как долго в своей практике эту программу используете? Кто-то кроме вас в компании её использует? Как вы работаете совместно? Вот эти детали интересны.
Про Артефакты тоже не понятно. Для разработчиков нужен swagger или openApi. А какой именно артефакт вы им передаеёте? json с мапингом? Как разработчики и тестировщики этими артефактами пользуются? Ну то есть, разработчик и на основе таблички может пишсать код... Как его жизнь от этого инструмента облегчается?
Мне, честно говоря, маркдауна на всё хватает. Ты просто подстраиваешься под его особенности и не пытаешься нарисовать в нём многомерную таблицу или типа того. Это позволяет подходить к написанию требований иначе, декомпозируя их и раскладывая по полочкам.
А вот то, что каждый, кто взял маркдаун за основу начинает напихивать в него собственную кастомизацию - это тригерит слегка. Яндекс свои правила использует, грамакс - свои. И никто даже не делает теги скрытыми(хотя это есть в маркдауне). В результате взаимной совместимости примерно ноль. Чтобы перенести маркдаун из яндекса в граммакс надо изрядно попотеть... А маркдаун из грамакса использовать где-то ещё (например просматривать из под гитлаба) тоже невозможно. Это расстраивает и добавляет "минусов" при выборе инструмента...
Также, встречал в своей практике low-code платформы, в котором аналогичным способом сразу генериться конечный код. Т.е. этот редактор, впринципе, можно развить до аналогичной low-code платформы. Чтобы на выходе были не файлики с маппингом, а готовый код метода.
Не совсем понятно, какой артефакт документации готовит этот инструмент.
В моей практике, такие маппинги чаще всего делаются на BFF слое. Где тупо надо дернуть несколько эндпоинтов подряд и из полученных данных собрать ответ. Для таких эндпоинтов создается описание метода, в котором и содержится последовательность вызовов, правила обработки ответов и сам маппинг.
Т.е. маппинг это только часть документации.
Как вы применяете ваш маппер в процессе разработки? Что вы в результате передаёте разработчикам и тестировщикам и что они с этим делают?
Авторы статьи предлагают врать на собеседованиях. Т.е. как бы все врут, во всех компаниях, и мы вам врём, вот и вы всем врите! А то минус получите и офер упустите!
Треш, честно говоря. Ужасный у вас мир, и к вам не хочется. Ни на собесы такие попасть, ни вашим советам следовать...
Я на собеседованиях ( с обеих сторон) стараюсь быть честным и откровенным. Чтобы потом не возникало вопросов "зачем я сюда пришёл" и "зачем мы его наняли". Я уверен, что я упускаю оферы. Ну и хорошо, я думаю... нафиг такие оферы, где тебя уже на пороге облопошили...
Я правильно понимаю, что компания, занимающаяся заказной разработкой, кому нужный квалифицированные спецы "недорого" публикует перевод статьи, основной посыл которой "соглашайтесь на меньшие деньги, разрабы"?
Поддерживаю. Статьи от ведущих учителей микрошкол по обучению войтивайтишников изрядно загадили ленту... Вся их суть в привлечении внимания к их каналу по продаже курсов. Но их не модерируют на Хабре от слова совсем.
Да, многие компании по прежнему под "Системным аналитиком" понимают человека-оркестор. И бизнес требования формализирует, CJM с макетами составит и требования к контракту и БД напишет, и роль проджекта на себя возьмёт, наладив процесс в команде... Иногда ещё и потестирует что нибудь.
Только это прошлый век организации разработки. В современных компаниях все эти роли разделены, и бизнес аналитик и системный аналитик это разные люди, изготавливающие разные артефакты документации и стоящие на разных этапах процесса.
Странно утверждать, что рынку нужны описанные выше фулстеки. Хотя, может оно и так, просто не в моей практике...
И поучаствовав в десятках собеседований SA с обоих сторон я могу утвержать, что они проходят совершенно иначе, чем описано у вас в статье. Никто не спрашивает ваше портфолио. Скорее вам дадут приближенную к реальности задачку и посмотрят, как вы рассуждаете. И попутно зададут полсотни технических вопросов. И если вы не знаете, чем отличается GET от POST, то вашему портфолио грош цена.
Нет разделения на бизнес процессы и системные процессы. Бизнес процессы не спроектированы отдельно. Сомнительный патерн использования диаграммы последовательности. В системную логику, где чаще всего и используется диаграмма последовательности, проектировщик даже не погружается, упоминуя её вскользь и перекладывая ответсвенность на разработчиков.
Для стартапа с mvp может и зайдёт, при условии что всё это будет выброшено после проверки гипотезы.
В современных крупных системах так никто не проектирует.
Мысль следующая: инклюд в plantuml и adoc работает по разному.
В adoc инклюдится текст файла. И только собранный текст отправляется на сервер, например кроки.
Можно подумать и сделать аналогичный механизм... сначала собирать инклюдами текст, а потом отправлять его на рендринг. Тогда не важно, есть ли доступ к самим файлам.
Честно говоря, очень поверхностно.
Аналогия со строительством моста не понятна. Процессы строительства больше перекликаются с процессом разработки, а не с процессом документирования по факту. С этой точки зрения, вы не строите мост, а восстанавливаете проектную документацию на этот мост после пожара в архиве. Берёте инженера с линейкой, и ходите и всё измеряете. Это больше похоже к.м.к.
В остальном, не понятна цель статьи. Запрос в гугле " кто такой техпис" даст примерно такую же информацию... Ощущение, что хотелось что-то написать и это была единственная тема, через которую можно упоминуть свой ТГ канал...
Ну так вы где вырасли? В тиньке??? Там замкнутая экосистема с весёлым матерком и сомнительными культурными ценностями. Зато расти там можно хоть каждые полгода. И это весь ваш IT опыт? Вы там на айтишников насмотрелись?
Я честно попробовал, но даже по инструкции ничего не получилось.
В статье нет примера результата. Оценить качество документации, которую подготавливает инструмент не получилось.
Формат docx широко распространён в узком кругу опрошенных. Хранить доку в docx это лет 15-20 назад было базой. Сейчас - кто во что горазд. Я например, продвигаю doc as code и пишу на markdown. Может имеет смысл присмотреться к другим форматам...
Вообще, openApi и swagger вполне достаточны для документирования. Примеры есть, подёргать можно. В дополнительном описании эндпоинтов может быть описана системная логика. Но вы такое описание из свагера не вытащите, это не возможно. Тогда встаёт вопрос: кто потребитель вашей документации и для чего она вообще нужна?
В развитых проектах, в отличии от "наколеночной разработки", сначала готовится документация, а потом пишется код. И опять таки встаёт вопрос: кто потребитель вашего инструмента, для кого вы его хотите сделать?
Ну и конкуренция с ИИ. Сейчас модели вполне сносно готовят документацию по эндпоинтам проходясь по коду и вытаскивая всю подноготную из системной логики.
Возможно, есть процессы, в которых данный инструмент будет полезен. Тогда, для продолжения работы, необходимо понимать, что это за процессы, как этот инструмент будет встроен в процесс и какие артефакты будет готовить и как будет их обновлять. Определится с тем, кто является потребителем самого инструмента и кто является потребителем результата его работы. И спросить не у всего сообщества (слишком широкий охват и большой процент нецелевой аудитории) а именно тех, для кого этот инструмент будет полезен.
Привет.
Я сам пишу спеки в doc-as-code давно.
Сейчас встал вопрос, а как затащить в подход и другие направления? По хорошему нужен редактор wysiwyg, работающий с git.
Яндекс.Вики работает на базе markdown, но хранит не в git.
Рассматриваю сейчас Gramax.
Собственно вопрос: что-то встречали похожее? Так чтобы и wysiwyg и markdown и хранить в git?
Я это к тому, что каждый артефакт документации имеет свой жизненный цикл. И если есть программа, генерирующая артефакт, то должна быть в программе поддержка этого жизненного цикла.
Если вы эти артефакты куда-то выкладываете, то как вы их потом обновляете? Как их обновляют другие аналитики?
И как эти артефакты упрощают дальнейшую разработку и тестирование?
Просто, если вы создали инструмент, который генерит всю ту-же табличку в конфе с маппингом, то чере 5-6 итераций правок станет понятно, что проще её обновлять в самой конфе, без дополнительных инструментов. Потому что будет вечный процесс: подгрузи актуальную версию, поправь её, выгрузи обратно. И если это правка в одном поле, то никто замарачиваться не будет...
С json, по большому счёту, тоже самое...
Соответственно и вопросы эти сводятся к одному: Вы как долго в своей практике эту программу используете? Кто-то кроме вас в компании её использует? Как вы работаете совместно?
Вот эти детали интересны.
Про Артефакты тоже не понятно. Для разработчиков нужен swagger или openApi. А какой именно артефакт вы им передаеёте? json с мапингом?
Как разработчики и тестировщики этими артефактами пользуются?
Ну то есть, разработчик и на основе таблички может пишсать код... Как его жизнь от этого инструмента облегчается?
Тогда давайте продолжим, чтобы понять ценность...
Вот у меня есть :
маппинг в программе
excel файл
json файл
Пришла новая задача, по которой мапинг надо изменить: добавить одно поле.
Вы это должны сделать сначала в программе, потом обновить excel в конфе, и json.
Как выглядит этот процесс, если работает другой аналитик? Он должен ваш маппинг сначала подгрузить себе?
Так а гит из коробки это всё умеет....
Мне, честно говоря, маркдауна на всё хватает. Ты просто подстраиваешься под его особенности и не пытаешься нарисовать в нём многомерную таблицу или типа того. Это позволяет подходить к написанию требований иначе, декомпозируя их и раскладывая по полочкам.
А вот то, что каждый, кто взял маркдаун за основу начинает напихивать в него собственную кастомизацию - это тригерит слегка. Яндекс свои правила использует, грамакс - свои. И никто даже не делает теги скрытыми(хотя это есть в маркдауне). В результате взаимной совместимости примерно ноль. Чтобы перенести маркдаун из яндекса в граммакс надо изрядно попотеть... А маркдаун из грамакса использовать где-то ещё (например просматривать из под гитлаба) тоже невозможно. Это расстраивает и добавляет "минусов" при выборе инструмента...
Также, встречал в своей практике low-code платформы, в котором аналогичным способом сразу генериться конечный код. Т.е. этот редактор, впринципе, можно развить до аналогичной low-code платформы. Чтобы на выходе были не файлики с маппингом, а готовый код метода.
Не совсем понятно, какой артефакт документации готовит этот инструмент.
В моей практике, такие маппинги чаще всего делаются на BFF слое. Где тупо надо дернуть несколько эндпоинтов подряд и из полученных данных собрать ответ. Для таких эндпоинтов создается описание метода, в котором и содержится последовательность вызовов, правила обработки ответов и сам маппинг.
Т.е. маппинг это только часть документации.
Как вы применяете ваш маппер в процессе разработки? Что вы в результате передаёте разработчикам и тестировщикам и что они с этим делают?
Авторы статьи предлагают врать на собеседованиях. Т.е. как бы все врут, во всех компаниях, и мы вам врём, вот и вы всем врите! А то минус получите и офер упустите!
Треш, честно говоря. Ужасный у вас мир, и к вам не хочется. Ни на собесы такие попасть, ни вашим советам следовать...
Я на собеседованиях ( с обеих сторон) стараюсь быть честным и откровенным. Чтобы потом не возникало вопросов "зачем я сюда пришёл" и "зачем мы его наняли". Я уверен, что я упускаю оферы. Ну и хорошо, я думаю... нафиг такие оферы, где тебя уже на пороге облопошили...
Я правильно понимаю, что компания, занимающаяся заказной разработкой, кому нужный квалифицированные спецы "недорого" публикует перевод статьи, основной посыл которой "соглашайтесь на меньшие деньги, разрабы"?
Я ничего не упустил?)))
Поддерживаю. Статьи от ведущих учителей микрошкол по обучению войтивайтишников изрядно загадили ленту... Вся их суть в привлечении внимания к их каналу по продаже курсов. Но их не модерируют на Хабре от слова совсем.
Вообще-то рынок сильно другой.
Да, многие компании по прежнему под "Системным аналитиком" понимают человека-оркестор. И бизнес требования формализирует, CJM с макетами составит и требования к контракту и БД напишет, и роль проджекта на себя возьмёт, наладив процесс в команде... Иногда ещё и потестирует что нибудь.
Только это прошлый век организации разработки. В современных компаниях все эти роли разделены, и бизнес аналитик и системный аналитик это разные люди, изготавливающие разные артефакты документации и стоящие на разных этапах процесса.
Странно утверждать, что рынку нужны описанные выше фулстеки. Хотя, может оно и так, просто не в моей практике...
И поучаствовав в десятках собеседований SA с обоих сторон я могу утвержать, что они проходят совершенно иначе, чем описано у вас в статье. Никто не спрашивает ваше портфолио. Скорее вам дадут приближенную к реальности задачку и посмотрят, как вы рассуждаете. И попутно зададут полсотни технических вопросов. И если вы не знаете, чем отличается GET от POST, то вашему портфолио грош цена.
Статью надо было назвать иначе: " Как успешно преодолеть трудности, которые вы сами себе создали?"
И самые здравые мысли, как обычно, в комментариях: "А как вы вообще дошли до точки, в которой куча бесценной информации лежит в одном человеке?"
Это какая-то мешанина из проектирвоания.
Нет разделения на бизнес процессы и системные процессы. Бизнес процессы не спроектированы отдельно. Сомнительный патерн использования диаграммы последовательности. В системную логику, где чаще всего и используется диаграмма последовательности, проектировщик даже не погружается, упоминуя её вскользь и перекладывая ответсвенность на разработчиков.
Для стартапа с mvp может и зайдёт, при условии что всё это будет выброшено после проверки гипотезы.
В современных крупных системах так никто не проектирует.
Надо фичу запилить)
Мысль следующая: инклюд в plantuml и adoc работает по разному.
В adoc инклюдится текст файла. И только собранный текст отправляется на сервер, например кроки.
Можно подумать и сделать аналогичный механизм... сначала собирать инклюдами текст, а потом отправлять его на рендринг. Тогда не важно, есть ли доступ к самим файлам.
Подскажите, есть ли поддержка операции include в файлах plantuml? У меня большинство сиквенс диаграмм сборные из разных частей.
Можно ли вставлять puml файлы в статьи на markdown? В gitlab мне для этого приходится asciidoc использовать.
Если поделитесь подробностями - буду признателен.