Вы никогда не думали, что делая подробное ТЗ вы делаете двойную работу? Вначале аналитик подробно описывает все алгоритмы и спецификации, а потом разработчик делает то же самое, но на другом языке.
Это некорректно сравнение. Разработчик производит код. Это результат.
Документация описывает этот код.
Вы же не будете утверждать, что план разводки розеток и сами провода, лежащие в стене, это одно и тоже???
Я пытаюсь себе представить аналогию с ремонтом. Вы взяли сантехника, электрика, и маляра и вовлекли в продумывание дизайна квартиры...
Сомнительная эффективность, как по мне.
Почему вы не стали выстраивать качественный процесс с системным анлаизом? Чтобы каждый занимался своим профессиональным делом, а не думал о "чужих" областях?
Вообще то, в крупняках и современных компаниях роли СА и БА разделены. И современные СА должны хорошо отвечать на тех. вопросы, а не рассказывать про сбор требований и их типы, и упоси ГОСТы. Если у вас спросили всё из этого списка, значит процессы в нанимающей компании уже давно морально умтарели.
Ну а если в вас это всё впихивают на курсе, значит вы выбрали не тот курс...
Вообще, в компаниях с современными процессами практикуют documentation first.
Т.е. сваггер появляется даже до начала разработки и всем участникам процесса контракт известен заранее.
При этом, одного сваггера недостаточно. Свагер описывает контракт взаимодействия, а не логику работы. Может быть два идентичных метода, возвращающие одинаковые объекты, но совершенно разные данные. Поэтому к каждому методу всё равно необходимо текстовое описание логики работы.
Вы на верном пути, но это только часть необходимой документации.
Компании, использующие современные процессы разработки давно разделили роли системного и бизнес аналитика. Статья скорее заирагивает деятельность бизнес аналитика или продуктового. На системных аналитиков вличние несколько иное.
Аналогия со строительством моста не понятна. Процессы строительства больше перекликаются с процессом разработки, а не с процессом документирования по факту. С этой точки зрения, вы не строите мост, а восстанавливаете проектную документацию на этот мост после пожара в архиве. Берёте инженера с линейкой, и ходите и всё измеряете. Это больше похоже к.м.к.
В остальном, не понятна цель статьи. Запрос в гугле " кто такой техпис" даст примерно такую же информацию... Ощущение, что хотелось что-то написать и это была единственная тема, через которую можно упоминуть свой ТГ канал...
Ну так вы где вырасли? В тиньке??? Там замкнутая экосистема с весёлым матерком и сомнительными культурными ценностями. Зато расти там можно хоть каждые полгода. И это весь ваш IT опыт? Вы там на айтишников насмотрелись?
Я честно попробовал, но даже по инструкции ничего не получилось.
В статье нет примера результата. Оценить качество документации, которую подготавливает инструмент не получилось.
Формат docx широко распространён в узком кругу опрошенных. Хранить доку в docx это лет 15-20 назад было базой. Сейчас - кто во что горазд. Я например, продвигаю doc as code и пишу на markdown. Может имеет смысл присмотреться к другим форматам...
Вообще, openApi и swagger вполне достаточны для документирования. Примеры есть, подёргать можно. В дополнительном описании эндпоинтов может быть описана системная логика. Но вы такое описание из свагера не вытащите, это не возможно. Тогда встаёт вопрос: кто потребитель вашей документации и для чего она вообще нужна?
В развитых проектах, в отличии от "наколеночной разработки", сначала готовится документация, а потом пишется код. И опять таки встаёт вопрос: кто потребитель вашего инструмента, для кого вы его хотите сделать?
Ну и конкуренция с ИИ. Сейчас модели вполне сносно готовят документацию по эндпоинтам проходясь по коду и вытаскивая всю подноготную из системной логики.
Возможно, есть процессы, в которых данный инструмент будет полезен. Тогда, для продолжения работы, необходимо понимать, что это за процессы, как этот инструмент будет встроен в процесс и какие артефакты будет готовить и как будет их обновлять. Определится с тем, кто является потребителем самого инструмента и кто является потребителем результата его работы. И спросить не у всего сообщества (слишком широкий охват и большой процент нецелевой аудитории) а именно тех, для кого этот инструмент будет полезен.
Я это к тому, что каждый артефакт документации имеет свой жизненный цикл. И если есть программа, генерирующая артефакт, то должна быть в программе поддержка этого жизненного цикла.
Если вы эти артефакты куда-то выкладываете, то как вы их потом обновляете? Как их обновляют другие аналитики? И как эти артефакты упрощают дальнейшую разработку и тестирование? Просто, если вы создали инструмент, который генерит всю ту-же табличку в конфе с маппингом, то чере 5-6 итераций правок станет понятно, что проще её обновлять в самой конфе, без дополнительных инструментов. Потому что будет вечный процесс: подгрузи актуальную версию, поправь её, выгрузи обратно. И если это правка в одном поле, то никто замарачиваться не будет... С json, по большому счёту, тоже самое...
Соответственно и вопросы эти сводятся к одному: Вы как долго в своей практике эту программу используете? Кто-то кроме вас в компании её использует? Как вы работаете совместно? Вот эти детали интересны.
Про Артефакты тоже не понятно. Для разработчиков нужен swagger или openApi. А какой именно артефакт вы им передаеёте? json с мапингом? Как разработчики и тестировщики этими артефактами пользуются? Ну то есть, разработчик и на основе таблички может пишсать код... Как его жизнь от этого инструмента облегчается?
Мне, честно говоря, маркдауна на всё хватает. Ты просто подстраиваешься под его особенности и не пытаешься нарисовать в нём многомерную таблицу или типа того. Это позволяет подходить к написанию требований иначе, декомпозируя их и раскладывая по полочкам.
А вот то, что каждый, кто взял маркдаун за основу начинает напихивать в него собственную кастомизацию - это тригерит слегка. Яндекс свои правила использует, грамакс - свои. И никто даже не делает теги скрытыми(хотя это есть в маркдауне). В результате взаимной совместимости примерно ноль. Чтобы перенести маркдаун из яндекса в граммакс надо изрядно попотеть... А маркдаун из грамакса использовать где-то ещё (например просматривать из под гитлаба) тоже невозможно. Это расстраивает и добавляет "минусов" при выборе инструмента...
Также, встречал в своей практике low-code платформы, в котором аналогичным способом сразу генериться конечный код. Т.е. этот редактор, впринципе, можно развить до аналогичной low-code платформы. Чтобы на выходе были не файлики с маппингом, а готовый код метода.
Не совсем понятно, какой артефакт документации готовит этот инструмент.
В моей практике, такие маппинги чаще всего делаются на BFF слое. Где тупо надо дернуть несколько эндпоинтов подряд и из полученных данных собрать ответ. Для таких эндпоинтов создается описание метода, в котором и содержится последовательность вызовов, правила обработки ответов и сам маппинг.
Т.е. маппинг это только часть документации.
Как вы применяете ваш маппер в процессе разработки? Что вы в результате передаёте разработчикам и тестировщикам и что они с этим делают?
Это некорректно сравнение. Разработчик производит код. Это результат.
Документация описывает этот код.
Вы же не будете утверждать, что план разводки розеток и сами провода, лежащие в стене, это одно и тоже???
Эмм... нет, это компании с незрелыми процессами разработки так работают.
Компании со зрелыми процессами давно работают с documentation first. А те кто хотят это делать быстро и эффективно реализуют его через doc as code.
Я пытаюсь себе представить аналогию с ремонтом. Вы взяли сантехника, электрика, и маляра и вовлекли в продумывание дизайна квартиры...
Сомнительная эффективность, как по мне.
Почему вы не стали выстраивать качественный процесс с системным анлаизом? Чтобы каждый занимался своим профессиональным делом, а не думал о "чужих" областях?
Вообще то, в крупняках и современных компаниях роли СА и БА разделены. И современные СА должны хорошо отвечать на тех. вопросы, а не рассказывать про сбор требований и их типы, и упоси ГОСТы. Если у вас спросили всё из этого списка, значит процессы в нанимающей компании уже давно морально умтарели.
Ну а если в вас это всё впихивают на курсе, значит вы выбрали не тот курс...
Вообще, в компаниях с современными процессами практикуют documentation first.
Т.е. сваггер появляется даже до начала разработки и всем участникам процесса контракт известен заранее.
При этом, одного сваггера недостаточно. Свагер описывает контракт взаимодействия, а не логику работы. Может быть два идентичных метода, возвращающие одинаковые объекты, но совершенно разные данные. Поэтому к каждому методу всё равно необходимо текстовое описание логики работы.
Вы на верном пути, но это только часть необходимой документации.
Очередная статья по продвижению тг канала...
Компании, использующие современные процессы разработки давно разделили роли системного и бизнес аналитика. Статья скорее заирагивает деятельность бизнес аналитика или продуктового. На системных аналитиков вличние несколько иное.
У меня просто два дополнительных мобильных экрана, каждый по 100$.
Ставлю один вертикально.
Всё.
Так много интересного можно написать про яхтинг. Даже про яхтинг в IT. Например, ребята организуют чудесную IT-регату.
А не вот это вот...
Проскролил. Даже на скролинг пожалел потраченного времени. Я не понимаю, зачем об ЭТОМ странном опыте писать на Хабре.
Честно говоря, очень поверхностно.
Аналогия со строительством моста не понятна. Процессы строительства больше перекликаются с процессом разработки, а не с процессом документирования по факту. С этой точки зрения, вы не строите мост, а восстанавливаете проектную документацию на этот мост после пожара в архиве. Берёте инженера с линейкой, и ходите и всё измеряете. Это больше похоже к.м.к.
В остальном, не понятна цель статьи. Запрос в гугле " кто такой техпис" даст примерно такую же информацию... Ощущение, что хотелось что-то написать и это была единственная тема, через которую можно упоминуть свой ТГ канал...
Ну так вы где вырасли? В тиньке??? Там замкнутая экосистема с весёлым матерком и сомнительными культурными ценностями. Зато расти там можно хоть каждые полгода. И это весь ваш 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 слое. Где тупо надо дернуть несколько эндпоинтов подряд и из полученных данных собрать ответ. Для таких эндпоинтов создается описание метода, в котором и содержится последовательность вызовов, правила обработки ответов и сам маппинг.
Т.е. маппинг это только часть документации.
Как вы применяете ваш маппер в процессе разработки? Что вы в результате передаёте разработчикам и тестировщикам и что они с этим делают?