Transcription
Всем доброго вечера. Не прошло и суток, как мы снова с вами на связи. И мы продолжаем готовиться к конференции КДФ, которая придёт на этих выходных в городе Новосибирск. И сегодня у нас в гостях аналитик Андрей Любарский, который на конференции КДФСТ будет проводить квартирник с темой, на которой будут обсуждаться вопросы документации. И не просто документации, а можно ли документацию превратить в код и будет ли это удобно работать как аналитикам, как разработчикам, так и другим участникам проектов по созданию информационных систем. И для того, чтобы поучаствовать в обсуждении, кто к нам придёт, сегодня Андрей подготовил небольшой теоретический материал, плюс рассказ о реальном внедрении данного подхода в своей компании. Итак, Андрей, тебе слово.
>> Да, добрый день. Спасибо большое. [откашливается] Рассказ не то, чтобы один, скорее несколько, э, так сказать, реальных историй. А о чём мы будем говорить? Во-первых, надо нормально представиться. Как сказали, меня зовут Любарский Андрей. Я работаю в Т-банке именно системным аналитиком. А достаточно стандартные вещи проектирую, делаю достаточно стандартные вещи, проектирую процессы, пишу документацию, помогаю разработчикам и всё остальное. А помимо этого ещё занимаюсь наукой. Так как наука оставила достаточно привела меня, можно сказать, в ИТ и оставила на мне, так сказать, неизгладимый след.
А о чём мы сегодня будем говорить? На самом деле, о достаточно стандартной и, э, всем знакомой ситуации, а когда, э, мы работаем без документации, что-то делаем и забываем. Достаточно всем знакомая, простая, обыденная ситуация, но, несмотря на то, что, казалось бы, к ней уже все привыкли, а так не должно быть. А как аналитики, мы пишем документацию, мы следим за её актуальностью, мы, э, над ней работаем, и это, в принципе, наш основной артефакт. Но мы достаточно часто попадаем в ситуацию, а когда документация не написана. Давайте задачу без анализа, надо скорее делать ходфикс. А, а как это вообще работает? А где это можно посмотреть? И всё начинает копиться снежным комом. И по итогу случается, что аналитик не просто сделал документацию и описал то, как всё работает в системе, он превращается в некоторый командный центр. И вот эта вот ситуация, которую все обычно стараются избегать, но она неизбежно происходит, когда вроде документация есть, но она какая-то не такая. Есть человек, который всё знает, и документ читать бесполезно. Нужно идти напрямую к человеку. Соответственно, новые задачи толком не спекаются. Аналитик занимается в основном поддержкой и пересказом документации, так как оно действительно работает. Оно всё не актуализировано. И получается, что основным артефактом работы аналитика становится не документация, а артефакт такой пропадает вообще. И основной функционал аналитика становится как работа чатбота, который может ответить на вопрос по приложению. И вроде как всегда хочется сказать: "Да, давайте напишем уже на какой-то страничке". Оно всё откладывается, откладывается, потому что либо нет ресурса, либо: "А зачем это делать? Всё равно никто не воспользуется, либо формат непонятный". И проблем-то на самом деле много. Но основная из них кроется в разночтении и в принципе в целеполагании такой документации.
А это на самом деле про что? Ещё один ещё одна стандартная ситуация, ещё один кейс а-а с параметром. Всем знакома та самая табличка с ээ параметрами контракта, где есть параметр, вот он тип и коварное поле обязательность, которое вроде кажется а это булева переменная, то есть она может быть либо да, либо нет, но в ней всегда демоны и кроются, потому что булева-то она булева, но на самом деле не до конца. Например, фронт-разработчик может подумать, что оно необязательное, и, значит, оно такое поле вообще приходить не будет. Бэкенд-разработчик может прочитать, что оно необязательное, и в том же поле отправлять null. И кажется, что вроде как должно работать, но, например, при разборе каких-то сбоев и кейсов непонятно, оно вообще было и оно просто из базы не вычиталось или его вообще не было. Это нормальное поведение. И возникает спор. И самое, наверное, для аналитика неприятное в этой ситуации, что вместо простого прочтения ТЗ документации начинается вот эта вот та самая консультация неприятная, которая отнимает ресурс, которая сдвигает все сроки, когда надо разбираться, а кто вообще прав, а что имелось в виду, а как вообще надо было. И в общем-то простая человеческая документация, она, э, перестаёт выполнять свою основную функцию.
Аа тут нужно сказать, что этот кейс не единичный. То есть, э, в связи с тем, что я как бы вращаюсь ещё и в науке, у меня достаточно много знакомых, которые, э, тоже работают аналитиками, и у всех одна и та же проблема, что документация готова, а разработчики либо её вообще читать не стали, ну, то есть сам разберусь, либо прочитали, но не так поняли, хотя казалось бы формат уже устаканен, и таких проблем быть не должно. И начинаются вот эти вот бесконечные перетягивания одеяла, конфликты. Ну, опять же, самое важное, что тратится ресурсы. То есть аналитик становится не человеком, который должен выстраивать процессы, коммуницировать между бизнесом и разработкой, а вот буквально чатботом и ходячей базой знаний на ножках, что, в общем-то, не так хорошо, как как казалось бы. А если там человек уходит из компании, то тоже непонятно, как восстанавливать все эти знания. Документацию надо переписывать. в общем, не оставляет никакого достоверного следа. А если он остаётся, то не факт, что а-а этот след точно будет распознан.
А почему, собственно, это происходит? А тут нужно обратиться немного к теории баз знаний и к разным потребителям этой документации. А аналитики работают обычно с двумя сущностями из представленных. Это, соответственно, контракт и документация на приложение, где складываются в основном user story, какие-то описания алгоритмов, а, и, в принципе, то, как должно работать. Однако артефактом, который, аэ, влияет непосредственно на работу всей программы, всей системы является сама кодовая база. И, как мы видим, а у нас даже потребители этой документации не пересекаются. То есть разработчики могут сказать: "Да, я в принципе и так в коде вижу, как он работает. Я по задаче понимаю, что надо изменить. Я сделаю это сам". Бизнес-заказчики видят документацию, которая написана, тоже говорят: "Всё хорошо". Из-за того, что нет пересечения между потребителями и даже артефактами, с которыми они работают, у нас начинают возникать проблемы. И, собственно, если это сказать кратко и лаконично, то код и документация на самом деле влияют друг на друга косвенно. То есть это происходит через человеческое восприятие. И таким образом, э, из-за разночтений, то есть действительно же опыт формирует то, как мы воспринимаем информацию. Из-за таких разночтений у нас, э, они начинают масштабироваться в сильное уже расхождение кода и непосредственно документации. Более того, если разбирать ситуацию, когда разработчик пишет документацию, то она, как правило, уходит в прошлое. И так как мы все аналитики, это вроде как наша зона ответственности, но а всё равно непонятно, как это всё примирить. То есть, да, мы разделили а всё приложение на две части в виде документации и непосредственно кода, но всё ещё непонятно, как без человеческих разночтений всё это согласовать. А так как у нас документация лежит на условной Wiki, разработчики работают в своём репозитории, либо они вообще не хотят лезть друг другу, либо они залезли, но ничего не поняли и сделали не так. И в принципе получается, что без какого-то вот какой-то жёсткой валидации машиночитаемой, всё это не имеет смысла, так как документация нормально не описывает работу системы, код работает не так, как хочет бизнес. И зачем вообще тогда мы всё это делаем?
Прежде чем идти к решению этого достаточно насущного вопроса, нужно понять, а как, в принципе, мы в такой точке оказались. То есть обычно э [откашливается] надо смотреть на инструменты, которыми мы пишем документацию. То есть понятно, что есть смысловая часть, но есть ещё и та самая вот информативная, те самые рюшечки, которые вот вроде как помогают восприятию информации. А первый у нас на сегодняшнем суде, так сказать, документация, это известный всем Confluence или Confluence, кстати, не уверен, как правильно ставить ударение. А в чём его непосредственное применение? Это всем широко известный, э, так сказать, процессор документации. И он влияет на всю нашу проблематику, то есть на нашу схемку, а исключительно тем, что есть некоторые макросы, которые позволяют помимо документации процессов и, в принципе, человекочитаемой документации вносить туда ещё и контракты, то есть прямо туда привязывать условные Swagger и оставлять такой технический след прямо э в Confluence. Однако это всё равно не решает глобальную проблему с тем, что кодовая база всё равно немножечко оторвана от работы аналитика и всё равно особо не соответствует. И как раз вот это переложение процессов в код происходит через то самое человекоизменяемое восприятие. Помимо всего этого можно выделить, что почему я сказал, что Confluence, собственно, всем знаком. Он сейчас много где используется из-за низкого порога входа. То есть это действительно очень простой с точки зрения вот UI и логики [откашливается] процессор документации. Хотя, ну да, будем называть это процессор документации. Там есть лёгкие возможности кастомизации, которыми все активно пользуются, и вроде, казалось бы, их хватает, но минусов у него, на самом деле сильно больше. То есть у него нет, как мы сказали, прямой связи с кодом. А это всё ещё отдельная страничка. То есть разработчики, как вот, например, у нас был кейс, что у меня многие разработчики в команде говорили, что я не хочу смотреть в Confluence, а я сам по коду всё пойму, а в крайнем случае по задачке разберусь, что нужно делать. Confluence мне непривычно, я привык с кодом работать. Также в Confluence достаточно сильно от структуры зависит. То есть, наверное, ну, не могу сказать за большинство, но я и некоторые мои знакомые сталкивались со структурной, так сказать, ситуацией, когда, казалось бы, найдена документация сервиса, нам нужно понять, что отвечает его метод. А оказывается, что метод находится в совершенно в другом месте, потому что методы сгруппированы по бизнес-процессам. Бизнес-процессы к сервисам не привязаны. В общем-то, такая спагетти-структура, она, э, очень сильно мешает восприятию и, в общем-то, всё равно полезнее не делает. И туда же можно ещё и отправить ссылки, так как часто бывает переиспользование какой-то логики, каких-то контрактов. С этим уже точно большинство наверняка сталкивалось. Э, и можно утонуть в ссылках. То есть обновление вот ссылок на Confluence, если это опять же без какого-то суперумного макроса происходит, то, э, это становится отдельной болью, когда скидывают документацию, а там просто шесть пунктов ссылок и каждая 404, потому что была перемещена. Тоже ситуация достаточно частая и достаточно неприятная. И казалось бы, минусов-то сильно больше, но из-за привычности и простоты у Confluence, Confluence всё ещё достаточно много активных пользователей, и многие всё ещё его выбирают, несмотря на то, что он как раз вот сильно обостряет проблему, о которой мы говорим в виде разночтения и каких-то личных предубеждений относительно документации.
И как раз про эти личные предубеждения, э, аналитики собрались и подумали, как это решать, и придумали, э, совместить чуть-чуть разработку и код, и, э, придумали так называемый AutoDoc или, э, APG. Там есть много ипостасей. Э, в общем-то, в общем случае это всё называется одним подходом Docs-as-Code, при котором документация пишется псевдокодом, то есть условным Markdown или AsciiDoc, а тоже живёт в репозитории. Туда уже сильно легче прикручиваются [откашливается] контракты в виде Swagger и всего остального. И казалось бы, вот почти решение, то есть и разработчики уже нос воротить не будут, потому что смотрите, это же репозиторий с кодом. Вот всё, как вы хотели. И версионировать это, казалось бы, сильно проще, так как это всё через Git и репозиторий работает. И вообще это почти полноценное соседнее [откашливается] приложение. Однако есть, а всё ещё некоторые минусы. А минусы, собственно, какие? Во-первых, если посмотреть на нашу схему, э здесь есть коварная, хитрая стрелочка иногда. Аэ почему иногда? Так как генерация именно из OpenAPI контракта, то есть из Swagger, не всегда работает хорошо. То есть, да, аналитик делает документацию на приложение, описывает в Markdown AutoDoc, там User Story и т.д. Также прописывает там же, в том же репозитории контракт. И после этого разработчики могут, опираясь на контракт, прикрутить автогенерацию. И вроде как при релизе документации всё будет обновляться. Но аа дело в том, что автогенераторы кода из OpenAPI всё ещё не очень хороши. То есть, э, не всегда они могут покрыть все недостающие кейсы, а они не всегда закрывают все нужные потребности, и поэтому стрелочка иногда она действительно иногда. То есть это подходит далеко не всем. И с та с такой проблемой как раз столкнулась наша команда, так как у нас были достаточно большие контракты-простыни, и мы сначала очень сильно устали их переводить в YAML. А мы потом пытались из OpenAPI генерировать код, но у него был так себе кодстайл, много генераторов перебрали и всё равно не подошло. И кажется, что AutoDoc, ну, простите, Doc-as-Code как формат вроде жизнеспособный, но очень-очень много он себе приносит сложностей. То есть это всё ещё отдельный репозиторий, то есть всё равно нужна какая-то ссылка а и разработчикам, и всем остальным. А он всё ещё зависит от структуры, пусть уже не так сильно, как Confluence, Confluence, так как всё ещё есть поиск и так далее, но всё равно это накладывает какие-то ограничения, и у него всё ещё нет прямой стабильной связи с кодом. Ну, несмотря на это, да, это хорошая такая игрушка, э, ну, как игрушка, достаточно серьёзная игрушка, которую можно уже сильнее, чем Confluence, Confluence кастомизировать. То есть там можно уже и свои плагины писать, и, в общем-то, сильно этим заниматься. Но, э, тут опять же, почему э не такое это распространённое популярное решение? Очень долго с ним разбираться надо. То есть пока все эти плагины, плагины настроятся, пока эти репозитории, пока произойдёт разбор, потом эта автогенерация, в общем-то, проблема всё равно не решается.
И кажется, что инструмента такого нет. А нам, наша основная задача какая? Поженить документацию и код. Сделать так, чтобы они друг на друга влияли, прямо друг с дружкой жили. И, э, у нас было машиновалидируемая связь между документацией и кодом. А для этого нужно, чтобы и формат документации был машинный, и, соответственно, сама связь как-то реализовывалась. И на самом деле решение такое есть, оно относительно свежее. Такой прямо новичок в документации. И называется он TypeSpec. Придуман он компанией Microsoft. [фыркает] Основная его суть заключается в написании, а всё всё ещё, наверное, всё-таки псевдокода на некотором аналоге TypeScript. А, и у него есть достаточно большое количество компиляторов для разных языков программирования. Из вот этого вот псевдокода можно достаточно стабильно и очень, э, вариативно, очень красиво генерировать и OpenAPI, то есть прямо-таки Swagger, генерировать и код клиента, и код сервера. Соответственно, э остаётся на фронтде только привязать кнопки к нужным методам, на бэкенде только логику, а аналитику, казалось бы, написать только вот этот компилятор TypeSpec. А, но опять же возникает небольшой нюанс. Так как мы говорили про документацию, у нас не закрывается плашечка с бизнес-документацией, с user story и всем прочим. И чтобы не распыляться, уже конкретно в нашей команде мы придумали дописать в TypeSpec целые вставки с Markdown файлами, где будут описаны те самые бизнес-процессы. Таким образом, мы получили полноценную, э, да, полноценный большой репозиторий. в котором у нас прямо на страничке с контрактом описывается его бизнес-логика. Прямо там есть непосредственно сам контракт, а все его поля. Его там можно и потестировать, как в Docas стандартном. И самое приятное, что из написанной документации напрямую генерируются куски кода и для фронтэнда, и для бэкенда, и с ними практически невозможно запутаться. Достаточно просто привязать бизнес-логику. Она и так в том же месте описана, а, и у нас даже прикручено, то есть релиз документации несёт за собой автоматический релиз фронтэнда и, соответственно, ну, требует, автоматически это не происходит пока только ручно, ручным способом, а потом релиз бэкенда. То есть у нас фронт-энд генерится непосредственно из документации, и там прямо связаны релизы. Поэтому, да, аналитик теперь тоже проводит релизы. Честно скажу, это довольно страшно. Опыт новый, опыт интересный, но и достаточно, кстати, приятный. Прямо чувствуется непосредственно влияние документации на продукт.
А как этот зверь TypeSpec выглядит? Вроде красиво всё рассказано. Может быть, там какая-то YAML-простыня или что-то сложное? На самом деле нет. Это выглядит очень компактно, очень приятно к чтению, но требует какой-никакой подготовки. А это всё ещё некоторое подобие TypeScript. Это основная прелесть TypeSpec заключается в полной отсутствии переиспользования. О, господи, полное отсутствие необходимости дублирования. Наоборот, переиспользование тут есть. А, создаётся модель, то есть условное DTO, а, которая потом будет, э, проливаться в код, а, и на фронт, и на бэкенд. И самое приятное, оно может наследоваться. А здесь поддерживается полиморфизм, а, пусть и с некоторыми оговорками, но там с каждой версией оно всё сильнее и сильнее улучшается. А дальше создаются модельки для ошибок и прямо описываются интерфейсы. То есть то, что отрисовано справа в виде Swagger - это на самом деле кусок кода слева. Если вы когда-либо работали с YAML-файлами OpenAPI, то есть писали свой голыми руками, такая API-шка выглядела бы, ну, явно не на 30 строк, там было бы побольше. А если оно использует, например, несколько моделек, то оно было бы сильно побольше. А тут мы создали одну сущность, везде её привязали. Максимум мы можем пронаследовать, это нам структурирует, но, соответственно, не так сильно всё усложнит. И, ну, с компактным представлением работать всегда проще. Плюс оно отрисовывается красиво. Но из минусов, опять же, нужно чуть-чуть вникнуть, как всё-таки работает этот код. И самое-самое неприятное, нужно уметь работать с ООП, так как теперь по сути те самые модели, которые будут написаны аналитиком, они будут автоматически проливаться в код в виде DTO. А нужно всё-таки соблюдать принципы ООП, которые приняты в команде, также принципы нейминга, э, и всё остальное. И приходится прямо достаточно серьёзно залезть на территорию, как теоретическую, так и практическую разработки и учить ООП. Тут опять же, собственно, опытом могу сказать из всех, наверное, сложностей перехода на TypeSpec, э, о которых мы чуть дальше будем говорить, самым неприятным всё-таки оказалось конкретно для меня необходимость учить ООП. У меня так сложилось, что я больше процедурно люблю программировать. И вот разбираться с полиморфизмом, наследованием и всеми принципами и правилами мне было трудновато. Но всё-таки легковесность и простота написания документации, ну, и, как ни странно, увеличение влияния на сам код всё-таки перевесило и, э, пришлось научиться.
Подытоживая, что мы только что проговорили, а у нас появляется прямая связь с кодом. То есть на основе документации, которую пишут аналитики, мы вроде как теперь можем генерировать код. А от структуры у нас всё ещё зависит человеческое восприятие, но оно не путает машинное восприятие. То есть мы избавляемся от вот этого человеческого разночтения, когда непонятно, что где лежит. Ну, это человеку непонятно, если код написан верно. Неважно, как он визуализирован. Главное, что, э, машинка всё правильно соберёт и переберёт в модельки на бэке или там модельки на фронте. Тут кто как привяжет. И всё также от Docas-as-Code этого подхода остаётся возможность кастомизации, потому что у нас ко всему этому TypeSpec прикручен уже упомянутый Docosaurus и а всё такие же возможности кастомизации. у нас остаются. То есть мы вроде как проблемку эту уже вот почти решили, но есть всё ещё небольшая проблемка, что это всё ещё отдельная ссылка и куча мелочей, которые вроде как э не являются не относятся к нашей проблеме напрямую, но о них всё-таки знать стоит и упомянуть их стоит. Во-первых, это очень высокий порог входа. То есть, если при обсуждении Confluence, Confluence мы, э, сказали, что это простой формат, и он такой популярный, потому что там красивый UI, с которым достаточно легко взаимодействовать, то здесь уже UI нет. Тут прямо нужно уметь в TypeScript, в ООП и нужно прямо достаточно сильно готовиться. Но опять же такой плавающий минус, потому что часто бывает, что многие разработчики переходят в системный анализ, вот там проблем вообще не будет. Там наоборот возвращение в родные пенаты. А плюс есть небольшой, а какая-то тавтология забавная п скорее ксиморон плюс есть небольшой минус, что TypeSpec всё-таки формат молодой, он ещё развивается, и у него бывают затыки с очень хитрым полиморфизмом. То есть мы с этим сталкивались, что у нас не работал полиморфизм при автогенерации контракта, где нужно было склеивать по условию, ну, достаточно большое количество кусков. Он клеился не очень хорошо, но над этим работают. То есть, если не ошибаюсь, самая актуальная версия TypeSpec вроде 1.5 на текущий момент, то есть это даже не 2.0, это всё ещё 1.0 с небольшим количеством минорных каких-то фиксов. И они довольно активно развиваются. Там довольно большое, как ни странно, комьюнити. И они вносят правки вот как раз с полиморфизмом. Там даже заводился вроде тикет, но его судьбе неизвестно. Мы по-другому переписали без полиморфизма модельки, и нас это спасло. И, э, ещё парочка проблем возникает, о которых мы как раз дальше и будем говорить, потому что они всё-таки достаточно важные, хоть и побочные. А, во-первых, непонятно, а кто теперь документацию должен писать? А, то есть аналитики вроде работают с процессами и пишут документацию, но по сути это же чистый код, который ещё и модели определяет, ещё и знания ООП требует. Так почему бы не разработчику этим заниматься? И тут опять же могут возникнуть какие-то э проблемки. Разработчики могут захотеть писать, захотеть больше самостоятельности или аналитики э могут отказаться такое делать. Тут опять же вопрос: кто такое писать должен. И самое важное, что на самом деле этап пусть поможет э примирить в конфликт разработки аналитики в проблеме разночтения документации, [откашливается] но не примирит её окончательно. То есть на самом деле -э такой формат не является, да и в принципе изменение формата документации - это не панацея от каких-то проблем. Оно не прямо излечит моментально все возникающие э междуусобицы. Он на самом деле поможет их подсветить и полечить только в некоторых моментах. То есть, на самом деле, нужно всё-таки смотреть в сторону процесса, чтобы изменить отношение к документации, когда разработчик её читать не хочет. Тут нужно это регламентировать процессом, но TypeSpec может в этом плане помочь, пусть и не окончательно лечить.
И когда мы думаем о том, стоит ли на такой формат переезжать, нужно понять, чего мы на самом деле сильнее боимся. У нас есть, с одной стороны, техническая сложность, что его надо разворачивать, надо к нему готовиться и надо аналитика как-то к нему подготавливать. А с другой стороны, опять же, ролевая, которую мы сказали, что а кто это вообще должен делать, есть опять же третья сторона, а как сейчас. И на самом деле здесь вопрос: чего вы сильнее боитесь? Там технически это освоить или непонятно, а кто это теперь будет делать? А готовы ли вы к каким-то изменениям или то, как сейчас на самом деле не так страшно? Ну, соответственно, если вы принимаете решение, что нет, как сейчас жить нельзя, мы хотим точно попробовать что-то новое, ну, хотя бы если оно точно не всё вылечит, то нам станет полегче, то, э, возникает, собственно, следующий вопрос, который, наверное, всегда возникает при изменении какого-то процесса, какого-то компонента работы. А вопрос довольно простой: а как переезжать? Потому что формат достаточно сильно отличается от Confluence, Confluence. А немного отличается от Docas-as-Code, который есть. И всё равно нужен какой-то ресурс, нужна какая-то стратегия переезда, стратегия миграции. И тут тоже можно, ну не можно, мы сейчас как раз разложим по полочкам, как это делать. А вариантов на самом деле есть три, я бы даже сказал с половинкой. 3 с половиной. Основное это перевозить только новые фичи. Ну не основное, скорее первое, которое в голову приходит. А также можно сделать пилот, потом его промасштабировать, если что-то понравится, не понравится. Можно перевести сервисы, где, например, ругаемся чаще всего, то есть где максимально какая-то так сложилось, что документация непонятная или наоборот он очень важный, и из-за этого там нужно, чтобы точно никогда э не возникало там какие-то проблемы багов. Ну и, соответственно, половинка как вариант - это самый хитрый невозможный эфемерный, перест, ну или сколько потребуется. А [откашливается] если говорить про каждый вариант, плюс-минус с каждым сталкивались у нас. А если говорить про первый вариант с новыми фичами, а, да, а это из плюсов, не, конечно же, это первый шаг в сторону чего-то нового. Это также какая-то лакмусовая бумажка. То есть, если что-то не нравится, мы можем отказаться. Но опять же минус, который, наверное, будет почти у всех вариантов, что нужно привыкать к новому формату, и фичи будут делаться долго. То есть, если это новые фичи, но какие-то горящие, а мы уже приняли, что все новые фичи мы точно делаем в TypeSpec, то будет неприятно, потому что нужно разбираться, нужно, соответственно, всё это переделывать, нужно переосмысливать то, как документация должна описываться. Если это новые фичи, например, в процессе отказа от Legacy, то не факт, что вообще переезд когда-то состоится, потому что мы вроде как всё подготовим, но у нас могут остаться какие-то старые фичи, может остаться Legacy, которые вроде как трогать особо не хочется. И
Вот мы навсегда застрянем в ситуации, когда у нас половина документации там, половина сям и вообще непонятно, как с этим быть.
Ну и самое, наверное, важное во всех переездах - это вопрос ресурса. То есть, ээ, из-за того, что ресурс всегда мало, в общем-то, ситуация стандартная, а тоже можем застрять посередине, потому что какую-то задачу для скорости в старом формате сделали, какую-то задачу делали долго и в новом, какую-то для удобства. И, э, никогда, собственно, старые совсем, э, задачки, старые совсем кусочки документации не перевезли, потому что, так сказать, руки не дошли, и на самом деле так всё может замереть.
У нас как раз были ребята, которые перевозили только новые фичи, но у них всё сложилось достаточно, а, приятно, достаточно благополучно. А они стали перевозить новые Фичи. У них до этого приложение небольшое было. То есть не такая были молодая развивающаяся команда. Они там, когда корфункционал сделали MVP, они у них была старая документация. И вот уже всё новое они начали делать в новом формате, поэтому им повезло. Но для каких-то приложений монстров такой формат, скорее всего, не подойдёт, потому что он с большой вероятностью затянется.
А второй э вариант, который мы обсуждали - это пилотого масштабирования. А вот здесь, наверное, самое приятное, что можно сравнивать. То есть, так как мы делаем не новые фичи, а уже имеющиеся, можно подготовить одну страничку в двух ипостасях или, например, сделать новую вариацию старой странички и прямо посравнивать, то есть вносить изменения и в новую, и в старую версию, и смотреть с какой версией возникнет меньше вопросов, с какой будет меньше багов, а какая, например, с какой документацией быстрее будет реализация. Всё-таки у нас автодоog и, в общем-то, релиз аналитики может зарелизить половина задач, но а всё те же минусы, то есть у нас задач всё ещё много и полного переезда можно не дождаться. И, наверное, самое неприятное, что нужно будет поддерживать как раз две документации. То есть, да, мы какую-то часть переписали в новом формате, вносим правки и туда, и туда. И опять же, это тоже влияет на ресурсы, то есть задачки будут делаться медленнее. То есть уже тут не только новые фичи, а конкретно те, которые затрагиваются.
Но здесь всегда есть хитрый ход перевести неиспользуемые какие-то фичимо, как на лакмусовую бумажку, всё ли хорошо. А тут стоит, наверное, говориться, что это не полноценный вариант переезда. Это как раз вариант, когда мы хотим просто попробовать, но не факт, что будем на это переезжать. Это скорее вариант тестирования, потому что, да, вот, э, мы перевели там пару страничек, нам всё понравилось, у нас всё классно, но переезжать некогда, ресурса просто нет. И да, мы в голове держим, что когда-нибудь надо, но всё ещё не переехали. Но почему это вынесено как отдельный вариант миграции? А такая история, ну, наполовинку у нас случилась, где мы сначала попробовали пару страничек в новом формате, а сказали: "Да, всё классно, мы будем продолжать". И отложили в бклок. То есть, э, так она в бэклоге и валялась до, соответственно, финального варианта, до которого мы дойдём. И в общем-то как раз такой пилот помог понять, что новый формат лучше, так как разработчики намного охотнее смотрят код в репозитории, чем ходит на конфлюнс.
Есть остался последний полноценный, так сказать, вариант - это перевозить только сервисы, где проблемы есть, а которые достаточно сложные, с которыми возникает больше всего споров. И тут тоже появляется возможность сравнивать документацию, но уже не прямо построчно. А тут, на самом деле, скорее по формату работы, по скорости, то есть на како вот, например, направляемом сервисе задачи могут быстрее делаться или на нём может стать меньше багов, он перестанет быть проблемным. И вроде как тогда понятно, что проблемка всё-таки была в документации, а не в чём-то ещё. То есть это прямо уже лакмусовая бумажка скорее на процесс. И это опять же вариант переезда такой Черкнорисовский, где всё-таки будет два вида документации, но зато он как такая аптечка быстрого реагирования поможет э разобраться с текущими проблемами.
Ну опять же э всё те же минусы сохраняются, кроме одного достаточно существенного, что будет целых два флоу работы с задачами. А, то есть, если при пилоте мы можем просто сделать новый формат документации, но, например, не подключать автогенерацию, просто посмотреть, э, в формате теста, как оно поработает, то здесь, а, появляется между сервисами два новых флоу. То есть, э, мы должны в одном случае понимать, что релиз документации влечёт за собой релизкода, в другом случае не влечёт. И если в команде два аналитика, то можно вроде как и разделить. Один там в таймпспике работает, второй по-старому. Если аналитик один, то там начинаются очень тяжёлый mind games, когда в каждой задаче надо подумать, а кто её будет в итоге релизить-то, аналитик или разработчик. И начинается та самая, а, проблема с распределением ролей.
Но прежде чем мы пойдём как раз к распределению ролей, есть половинчатый вариант, который самый интересный. Это просто остановить всю работу и сказать: "Ну всё, стоп, мы переезжаем". А это как раз тот вариант, который благополучно случился у нас. А на нас обрушился счастливый период, когда, так сказать, можно подышать и задач было не гигантское количество, а мы прямо решили, что по ресурсам мы вывезем полноценный переезд. А мы до этого, как я говорил ранее, сделали пилот. Нас нам очень повезло. Нам дали энное количество времени на переезд. Мы смогли перевести всю документацию в новый формат. Аэ, у нас на тот момент был один сервис, и нам всё понравилось. Э, кроме одного момента, что пути назад нет. То есть, да, мы согласовали, нам всё нравилось, но когда это всё размасштабировалось и всё доросло, а у нас иногда возникают недовольные возгласы, что мне не очень хочется запускать пайплайн, чтобы посмотреть, как будет документация выглядеть. Вот лучше бы на вики остались. Там вообще всё сразу видно. Вот эта вот разноцветная радуга с изменениями, мне её не хватает. Но это больше в формате ворчания. Это всё равно, э, люди не отказываются от удобства от таймспека, что теперь релиз документации влечёт релиз куска кода.
А и, собственно, раз уж мы про релиз это и заговорили, а на самом деле, а кто релиз должен проводить? То есть, казалось бы, разработчики пишут код, они в релизет. Аналитики делают документацию, по документации пишется код. А у нас теперь оказывается, что аналитик пишет документацию, которая сама код релизит, ну, его кусок. Второй кусок пишет разработчик, и кажется, что аналитик просто отжимает хлеб у разработчика. И, в общем-то, и разработчик такую документацию может написать. просто модельку поп составить, все их там пронаследовать, между ними ещё накидать из задачи userсто и в общем-то кажется всё. То есть аналитик-то участвовать в этом не должен, но возникают вопросы: а как же бизнес-стории и так далее?
И начинается известный всем, ну, известно большинство, наверное, фрагмент из мультика про Лёша Поповича, где надо было сходить проверить страшный дом. И, соответственно, Алёша богатырь, он главный герой, он погибнуть не может. Любава, невеста главного героя, они должны пожениться, всё должно быть у них хорошо. Моисея я не отдам, потому что он мне нравится. Вот остаётся либо ты, либо бабка. И, в общем-то, обычно все вот эти проволочки процессные выпадают на аналитика, но на самом деле это не совсем правильно. Тут надо вспомнить, что, э, оговаривались в некоторых местах про изменение процесса и кажется, что нужно лечить процесс.
В общем-то, тут должна раскрыться основная соль, наверное, сегодняшнего вебинара в том, что документацию должны писать все, кто может. А в каком формате? Аналитик, например, разбирается в процессах. Он знает, как сервисы должны, что должны сервисы [откашливается] друг другу передать, знает контракты, знает модели. И, например, в какой-то большой задаче а аналитик всё это описывает. Однако есть какие-то мелкие задачи, в которых разработчик прочитал задачу и увидел, что спецификацию сделал довольно быстро. То есть надо всего один параметр задачи поменять, а что аналитика-то и дёргать. Казалось бы, и так всё понятно. Разработчик тогда пишет, собственно, самостоятельно делает Рспецификацию, а и у него не будет какого-то отвращения, что это конфлюнс и русский язык, потому что на самом деле это обычный код. Аэ также бизнес-аналитики могут залезть в этот же репозиторий и попросить сделать РМ с куском текста, потому что вот смотрите, у меня есть usеer story, а я могу её либо сам залить, либо вы там с мэром. И в таком формате кажется, что проблема-то и решена. То есть каждый, что может, то и делает.
И на самом деле вот это изменение нашу команду и полечило, потому что у нас очень часто была проблема, как на одном из метапов в нашей компании, как раз посвящённой DOCS коду. У всех спрашивали: "А какой у вас в команде подход: Doc first или CDF first?" И все очень красиво рассказывали, что у нас doкфрст, разработчики у нас ждут документацию, там вносят правки, а вот у нас в команде, например, был кто громчерит first, то есть кто докажет свою правоту, так и будет сделано. И там и документация могла по коду дописаться, и, соответственно, иногда код писался по документации, в которой, например, не нашли какую-то неточность, потому что пока ругались-то особо и не смотрели. И на самом деле внедрение такой документации, которая, казалось бы, открыта всем, очень сильно нас полечила. И у нас случилось как раз вот разделение, которое я озвучил, что какие-то совсем мелкие задачи, где, ну, вот там не доследили, нужно ещё один параметр вернуть. Их может разработчик полностью самостоятельно внести это всё в документацию, даже без какого-то бурчания, то есть просто с пульт репозиторий внести и оформить МР. Дело буквально 2 секунд, даже не выходя из рабочего инструмента из аналитику достаются обычно задачки побольше, где всё-таки надо с процессами повозиться, где уже чуть больше надо вникать в сущности и в какие-то бизнес-ограничения. И у нас, на самом деле, из-за этого кончились конфликты относительно документации и как сделать правильней, потому что тот, кто видит, как сделать правильней, просто делает МР, приносит его на ревью и вот и всё. То есть аналитик больше не страдает от количества больших тряпок в сторону: "А поправь там, а поправь сям". А я вот знаю, что здесь надо сделать лучше. Ну, знаешь, лучше, так сделай, потому что на самом деле всё это ведёт к довольно простому тезису, а к которому мы, собственно, с внедрением такого подхода и пришли, что разработка любого IT-продукта - это не только приложение для клиентов компании, ну или там, ну да, для клиентов компании. Это на самом деле всегда разработка двух приложений, а скорее даже двух продуктов, где один для непосредственных клиентов, а второй для внутренних пользователей. Просто к нему обычно требования-то и не пишутся. Обычно доку все говорят: "Ну, документация там нужна для онбординга, для какого-то наследственности, для отслеживания чего-то". И на самом деле, э, да, так и есть, но это всё является требованиями к внутреннему тому самому продукту, что она должна быть понятна человеку, который приходит вот недавно, что там должно быть указано всё подробно и разъяснено. Никто отдельно не выделяет аналитика на такой продукт, никто отдельно не пишет к нему требования, но к нему внезапно все обращаются, когда что-то идёт не так. к нему обращаются внезапно, когда случается онбординг и приходит кто-то новый в команду или когда человек, который работал над каким-то проектом, уходит и надо понять, а как оно вообще работает. То есть это на самом деле такой же продукт, как и вот основное приложение, которое делается. Просто у него потребители - это люди внутри компании, которые, собственно, с вами работают или которые будут участвовать в вашей команде.
Аа да. про, кстати, людей, которые работают с вами. А это, в том числе и для них удобно, так как в новом формате у нас можно тестировать ручки. У нас были живые истории, когда к нам приходили ребята и говорили, как у вас удобно вместо условной Вики мы можем сразу потестировать ваши методы. У нас можем сразу понять, подходит нам, не подходит, и нам даже не приходится вас дёргать.
И возвращаясь к изначальной подводке, с которой всё начиналось, что аналитик - это ходячая база знаний на ножках, теперь, во-первых, вся команда отвечает за всю вашу базу знаний, и она теперь не на ножках, а на самом деле на под пайплайнах гита и прямо отдельный продукт. И это теперь действительно не человек, а вот что-то машинное, какая-то машиночитаемая информация.
И как раз продолжая тему, что документация теперь - это не человек на ножках, а какая-то условная машина, а какой-то условный не чатбот, а сборник. Возникает вопрос: а можно ли её сделать в итоге чатботом? Ну, в конце концов, 2026 год, а всем сейчас, э, нужно использовать lм. У многих есть какие-то метрики в виде там AI, AI AI adoption, то есть всем следят, чтобы нейросети упрощались всем жизнь, всем предлагают их использовать. И нужно, конечно же, эту тему обсудить, потому что, да, в работе аналитика и использовать, если мы говорим не про диаграммы, а про куски текста, достаточно сложно, потому что чаще всего излагаем алгоритмы на русском языке, а в любом случае человекочитаемый язык для нейронки всегда достаточно сложен и в понимании, и в написании. и добиться достаточно слаженного алгоритма и хорошей документации на русском языке, ну, вот этим вот человеческим текстом, может быть довольно сложно.
Поэтому, а, мы переходим в формат Тайпспека, где документация уже становится не классическим деревом, как на конфлюенсе, где непонятно что взять, где нужно понимать, что всё-таки слово значит, чтобы понять, что там лежит. А мы переходим в формат кода. А, а машиночитаемые форматы с ЛМ всегда дружат сильнее. А тут могу по собственному опыту сказать, что с тепспеком LЛM дружит сильно лучше, чем и с Маркдауном, и с конфлюенсом, конфлюнсом, и с Аскидоком, потому что в Тайпспеке, а в контрактах именно не используется вообще человекачитаемый язык. Там всегда strн in, то есть машиночитаемые вещи, а поля тоже машино читаемые и полиморфизм, и наследование, и вход-выход. То есть это всегда машино читаемое какое-то описание. Поэтому аm достаточно хорошо его кушает и в том числе хорошо воспроизводит.
Более того, а мы недавно пробовали тестировать такую документацию через LLM. То есть мы предлагали на основании ещё и куска Markдаун текста написать код и посмотреть, справится ли она действительно. А результаты были так себе. Мы достаточно сложный туда кусок логики загрузили, но, э, в любом случае это открывает некоторые возможности для а очень-очень сильного вайб-кодинга, где помимо простого понимания, ну, то есть простого промпта, вы закидываете в ЛМ уже контракт готовый, под который нужно только бизнес-логику сгенерировать, написать. И это, на самом деле, достаточно непаханное поле. То есть здесь можно ещё много над этим рассуждать, но возвращаясь к именно вебинару, возникает достаточно простой вопрос: а вот мы навайп-кодили и контракт, и там какой-то кусок бизнес-логики, и вообще у нас аналитик всё через это делает, он кидается только промктами. Возникает вопрос: а если документация такая, ну, сгенерированная будет кривой, к кому нам тогда идти с претензиями? Казалось бы, а, вроде её сгенерировалам, надо обращаться к ней, но пром-то в неё вроде закинул аналитик, по идее виноват он. А проверяли-то это вроде разработчики на ревью? И почему они не заметили?
Возникает достаточно открытый вопрос. Мы с таким вопросом на своём опыте тоже столкнулись, потому что произошла ситуация, что нам пришли в ответственность сервис от другой команды, где документацию, э, вайп-кодили, то есть там как это иронично сказали, это назывался вайпспека. И хороший вопрос, а к кому обращаться, что документация так себе, потому что вроде код написан, вроде код работает. Да, он не соответствует документации, но вроде работает. Документация особо не читается, но всё ещё она есть и вроде можно куда-то вносить. И, в общем-то, и претензии сложно выдвинуть, но сказать тебе хочется и к кому туда обращаться. То есть вроде к аналитику, но он свою работу сделал, документация написана, работает. Ну, с косяками, но вроде работает. Разработчики смогли по ней разобраться? смогли, правда, без неё разрабатывали, но вроде разработано же как надо. И возникает очень сложная странная ситуация, где вроде номинально-то всё выполнено, а на самом деле основной эффект не достигнут. То есть документация кода не соответствует, ничего толком не отражает. А как работает, знают только разработчики, и только свой кусок бизнес-логики. Общий процесс неизвестен. И, в общем-то, ситуация на самом деле печальная.
К чему это всё было сказано? К тому, что ответственность за LLM-документацию, это ещё предстоит выяснять, потому что кейсы такие достаточно редкие, где полностью документация сгенерирована, но уже, наверное, стоит об этом думать. И если мы всё-таки прийдём к ситуации, которая была описана с полнейшим вайпкодингом на основе вот контрактов и репозитория в тайпспеке, то этот вопрос будет, наверное, ключевым. Ответ на него сейчас давать достаточно сложно, но нужно держать в голове, что он будет всплывать. И всплывать он будет очень и очень скоро.
А последнее, о чём стоит поговорить, если мы уж говорим про изменение процессов, про документацию, про, а, новые форматы и достаточно ресурсозатратные переезды, но тут, наверное, мы завершаем вопросом, который всегда у аналитиков возникает сначала: "А зачем нам это всё нужно делать?" А да, у нас процесс плохой. Ну, а чем оно поможет? А как мы поймём, что оно помогло? То есть как измерить всё-таки практическую пользу и как понять, что у нас вот этот вот формат документации, он нам подходит, он что-то нам помог изменить. И как понять, что всё, что мы делали, это на самом деле не зря. Да, мы хотели полечить, но непонятно, полечили или нет. То есть какие-то эмпирические метрики, а мы всё-таки э работаем с кодом, а как это, архетип человек знак. хочется каких-то циферок, то есть хочется какой-то статистики.
А есть стандартная пачка метрик, которую можно посмотреть через призму новой документации. И, наверное, первая основная, не самая показательная - это доля задач с документации в коде. Почему она не самая показательная? Она, на самом деле, не сказать, что сильно влияет на качество. То есть, да, у нас могло стать больше задач, которые сделаны в коде, но конкретно их количество ни на что не влияет. Да, их стало больше, но а это может говорить только об адопшене нового формата, то есть о том, что мы его усвоили, и чем больше их становится, значит, тем э роднее нам становится наш новый формат. Всё равно помимо вот этой вот доли задачи нужно смотреть какие-то связанные с ней метрики. То есть когда мы поймём, что у нас она не скачет, у нас стабильно. Вот если, например, если два аналитика, то 50 на50. У нас там один аналитик в новом формате, один аналитик в старом. Если у нас один аналитик, мы увидели, что у нас там все сервисы переехали, у нас такая метрика стабилизировалась. То есть она не является показательной, но она является стартовой для понимания того, насколько нам просто. Если мы видим, что она не растёт, то есть у нас там стабильно одна задачка в месяц, чтобы она вообще не падала, а есть смысл спросить всё-таки у аналитиков: "А вам что-то не ра?" Ну, что вам не нравится? А почему как бы не продолжаете такой формат? То есть что не устраивает? То есть как-то это разбираться. А когда у нас вот стабильно на каком-то сервисе все задачи с кодом, тогда можно уже смотреть на что это повлияло. То есть это такая метрика, от которой мы отталкиваемся уже при составлении какой-то статистики.
А есть ещё интересная э показатель такой, как время на согласование. А всё-таки процесс ревe мы особо не освещали, но в формате метрики о нём стоит поговорить. А стоит понимать, что из-за нового формата сначала оно вырастет. То есть, э, понятно, что приходит на регио аналитику не с стандартной викистраничкой, а внезапно ссылкой на МР. Вот тут, конечно, глаза у всех и квадратиятся, и сначала будет непонятно, как это смотреть. Нас, на самом деле, до сих пор эта ситуация сохраняется. Мы уже, кстати, почти как год переехали на тепспек. И всё равно у многих ребят в команде каждый раз квадратные глаза, когда я приношу на согласование именно МР, а не страничку, всё равно глаза квадратные. И каждый раз, э, вопросик: "А как это мне посмотреть? Э а как мне запустить тестовый стенс с этой документацией?" Всё равно некоторые упорные не хотят это признавать, хотя соглашаются, что это удобней, но всё равно всё ещё непривычно, потому что как бы чем больше опыта с конфлинко конфлюенсом, в принципе, работа аналитиком, тем сложнее переключаться на новые форматы. Аа также эта метрика может показывать очень неприятную вещь, если она, например, растёт, а у нас там какие-то интеграционники с соседними командами проводятся, то, э, соседня команды, у них тоже глаза, соответственно, оквадратятся. Они тоже будут долго с этим разбираться. А единственное решение относительно вот этого вот большого разрыва в самом начале, что такую метрику стоит отслеживать тоже спустя какое-то время. То есть когда мы, например, уже увидели, что у нас стабилизировалась доля задачи документации в коде, мы увидели, что временно согласование стало падать, важно уже на горизонте какого-то вот энного количества дней смотреть, что у нас оно стало меньше, чем было до внедрения. То есть вот этот вот кусок с первоначальным скачком, его нужно вырезать, потому что, понятно, он как бы стандартный, он довольно легко объяснимый. И, наверное, самый большой камень в огород этой метрики, что она не столько от документации зависит, от культуры ревью и от процессов. Потому что если разработчик в принципе не склонен сильно торопиться, делать ревью, и в ревью достаточно затягиваться в команде, то на самом деле новая документация а может [откашливается] этому не помочь. То есть, например, разработчик долго шёл до вики страницы, ровно также он долго будет идти до мра. Поэтому, на самом деле, это не совсем панацея, но всё равно метрика может быть довольно полезной, показать ускорение какого-то процесса.
Есть ещё параметрик, на которые стоит смотреть. Они уже чуть более конкретные, чем предыдущие. А самая, наверное, первая, которая пришла всем в голову - это уменьшение багов. А когда багов становится меньше, мы все радуемся. И это может быть заслуга как раз документации. Она точно влияет на качество, а-а, ну, может показывать достаточно неприятные моменты. То есть >> [фыркает] >> она, например, не изменится, если проблема была не в формате документации, а в коммуникации. То есть, если у нас при коммуникации возникают проблемки именно вот между разработкой и аналитикой, то мы, например, новой документацией не полечим коммуникацию. Багов всё будет столько же, потому что продолжится ругонь, только уже Итак, продолжаем. Аа остановились мы на ругане. Если у нас эта ругонь остаётся, только она просто переезжает в мёшреквесты и в комментарии в гите тогда, соответственно, багов всё равно не изменится. А если мы там поменяли процессы, как-то всех помирили, а или, например, у нас проблема была действительно в документации, то количество багов должно упасть. Единственный нюанс, который в эту метрику, опять же, не позволяет её назвать идеальной, это её измерение. А баги в любом случае могут быть не связаны с документацией. Это могут быть какие-то баги инфраструктуры, это могут быть баги именно вот, которые нашлись в коде, когда действительно разработчик, а при реализации бизнес-логики там в какую-то гонку упёрся или возникла проблема там с какими-то типами данных именно вот при перекладывании [откашливается] под капотом, то это действительно документация, это не проблема документации. Это всё такой же баг. И это я говорю к тому, что измерить уменьшение багов можно только, если вы их типизируете. То есть вы выделяете, что там есть какой-то там баг аналитики, баг коммуникации, баг разработки. И вот если у нас баги аналитики снижаются, то тут уже это хорошо. Баги разработки тоже могут снизиться, но, соответственно, некритично. То есть, видите, даже непонятно к какому типу относить такие баги. И в любом случае, чтобы это снижение точно точно определить, нужно проводить достаточно сильный анализ по багам, на который не всегда есть ресурсы, не всегда понятно, как его делать. То есть это прямо нужно очень сильно удариться в таск-менеджмент.
И, наверное, самая метрика сложная по измерению, ну, наверное, самая понятная. Это удовлетворённость команды. А это очень не цифровая метрика, это чистая эмпирика. А непонятно, как её нормально померить. То есть это могут быть какие-то каздевы. То есть в числах это выразить достаточно сложно, потому что опросы с предложением поставить от одного до десяти не всегда корректные, не всегда конкретные, когда человек ставит там 3 из дети, но я бы поставил пять. В общем, такие моменты вообще сложно перевести в цифры. Э также достаточно сложно её скоррелировать со скоростью выполнения задачи. То есть да, у нас 10 из де, но, э, скорость выполнения и выросла, то есть и непонятно, в общем-то, зачем мы её внедряли. Вроде как и на качество оно не влияет. А и делать её довольно сложно. То есть это прийти к
человеку, порасспрашивать его и, в общем-то, непонятно зачем такую собирать. Но есть один достаточно большой плюс.
Если возникали проблемы с коммуникацией и разработчики как раз говорили, что да, я не хочу лезть в конфликт, ээ я вот только в репозиториях работаю, и действительно аналитики там шипели, что разработчики всё неправильно в конфликте пишут, то с внедрением документации никакая метрика может и не поменяться. Но если вырастет удовлетворённость команды, а у вас там перестали все ссориться, а нашёлся какой-то общий язык. И даже несмотря на то, что, казалось бы, работать лучше не стало, если удовлетворённость команды выросла, это уже какой-то прогресс. То есть это такая спасительная последняя метрика, по которой даже если ничего не изменилось, можно сказать: "Да, мы делали это не зря". Потому что теперь у нас хотя бы членам команды работать стало комфортно. И даже если процесс не поменялся, даже если там багов не стало меньше, как минимум людям стало работать удобней, а это, ну, хоть что-то, хоть какие-то приятности, хоть зачем-то мы это сделали.
Другой вопрос, во что вы целитесь? То есть при внедрении документации нужно преследовать какую-то цель. И пока только понятно, что цель всегда может быть расплывчатой. Мы хотим там что-то посмотреть, что-то полечить. В любом случае здесь стоит только опереться на собственный опыт. У нас действительно со внедрением такой документации сильно полечились процессы, потому что мраз разработчики смотрят намного охотнее, чем Вики. У нас ускорился процесс поставки задач. У нас сильно разделилась разделились зоны ответственности, аа у нас разделились очень сильна. Из-за этого задачи стали делаться быстрее. То есть разработка может не отвлекаться на какие-то там созвоны по мелочам, где надо посмотреть там внедрение одного поля на вики. Ну, как бы это достаточно странное мелкое ревью. А у нас разработчики действительно работают все в девлекаются, если что. Сами провят документацию. Аналитик проверяет. Ну, аф на ставит. Аналитики теперь ведут большую архитектурную документацию в мэрах, и разработчики прямо не вылезая изда её смотрят. У нас действительно сильно ускорились процессы, они стали сильно качественнее, потому что у нас действительно уменьшились баги аналитики, стало меньше человеческих разночтений, так как у разработчиков теперь при релизе всё само выплывает в код. И по сути, э, часть работы теперь переложена на аналитика, а часть аналитика маленькая, переложено на разработчика. Из-за вот этого вот шифта в зонах ответственности, а команда стала работать быстрее, что, в принципе, достаточно полезный результат.
А подытоживая всё, о чём мы сегодня поговорили, выяснили, что на самом деле согласованная документация нужна, важна. и достаточно серьёзный, полезный артефакт, над которым работает целая профессия. Посмотрели на текущие форматы, выяснили, как они могут мешать согласованной документации или пытаться ей помогать, и посмотрели на целый новый формат, который, казалось бы, за согласованную документацию и очень-очень сильно ей помогает. А разобрали, как можно перестроить процесс, чтобы ускориться, если всё-таки написание документации и чтение разработчиками иногда вызывает боль и истерику. А посмотрели, как это можно перестроить, перекинуть обязанности, переиграть и каким инструментом, собственно, для этого можно воспользоваться. и выяснили, что документация - это не просто сбоку припёк от продукта основного, а целый отдельный необходимый продукт для внутреннего пользования, над которым нужно работать также тщательно и за который ответственно вся команда. Собственно, поэтому стоит выбирать форматы, с которыми удобно работать всей команде и с которыми разберётся тоже вся команда. А на этом, а, наверное, да, не наверное, а точно всё. Спасибо всем большое за внимание.
>> Да, у нас есть вопросы, поэтому я озвучу тебя, Андрей, а ты на них ответишь.
>> Кстати, по обсуждению в чате тема достаточно актуальна, что касается документации, сделать её более полезной, читабельной. и работа пригодной. Поэтому, ещё раз повторяю, обсуждение по теме очное состоится на конференции КДФС в ближайшие выходные, поэтому у кого есть возможность, приходите, и там вы можете поделиться своим опытом, рассказать свои истории, задать вопросы, поделиться проблемами, в общем, обсудить, что мы всегда и делаем на квартирников. Ну, а пока ответы, э-э, вернее, вопросы и ответы на них.
Итак, Антон спрашивает: "А не пробовали ли использовать план для документирования бизнес-логики?"
А, пробовали, а, активно используем. А, но в ПНТмейле достаточно сложно описывать большое количество нюансов. То есть у нас бывает логика, в которой нужно прямо прописывать, как собираются маппинги. И там есть большое количество преобразований. Вот, например, сегодня буквально занимался задачей, где нужно было конкатинировать там 11 полей в ПД, каждая по своему, э, правилу, с условием. И в Плантюмейле, ну, не в ПНТмейле, во всём алгоритме, это был шестой пункт из одиннадцати. Соответственно, в ПНТмеле такой большой текст, он сильно бы располся. А, но в тайпспеке поддерживаются все те же плагины докузауруса и так далее. И Plant Umail диаграммы у нас там тоже живут. И для нас это тоже, кстати, стало большим плюсом, потому что раньше планмельди диаграммки жили локально у одного аналитика на компьютере. Теперь они все в одном репозитории, в одном конкретном месте. И прямо там история изменений.
Я я надеюсь.
>> Здорово. Ну, если есть дополнительные вопросы, то пишите в тот же файл. И Роман спрашивает, ну, в продолжение предыдущего, но только он говорит про инструмент, как я понял, Mirmate, а для тех же диаграмм,
>> да?
А Mirmate тоже есть. У нас прикручен PL UML плагин, так как нам удобнее с ПНОм пользоваться. Но, кстати, сейчас боюсь соврать. У нас в компании были ребята, которые наоборот в мермейде как раз рисуют, и у них тоже в тепспек оно прикручено. У них прямо страничка генериция, где контракт, потом алгоритм и внизу как размей диаграммка. То есть, да, это всё там тоже можно. Это всё просто вместе с имеющимися алгоритмами лежит.
>> Да, прямо напрашивается отдельный мастер-класс по использованию Плантуль и мермейда в качестве дополнения к Тайспеку.
А, Антон опять спрашивает: "Если разработчик меняет контракт при реализации, как это синхнизируется обратно в тай спеке?"
А тут, на самом деле, очень больно вопрос. Всё-таки подловили. Если он меняется в коде, но не меняется в тайпспеке, то такой синхронизации нет. А, да, документация влияет на код, но код на документацию всё ещё не влияет. Там, к сожалению, стрелка односторонняя. То есть разработчик всё ещё волен сделать код несоответствующий документации, но, например, при следующем релизе документации это всё перезатрётся и может выпасть в ошибку. То есть тут в любом случае до разработчика нужно донести, что теперь такие вещи будут больнее, потому что если аналитик придёт со следующей задачей, у него не будет этого в доке, там случится что-то очень страшное. А, но это если мы говорим про контракты, то есть там просто произойдёт перезатирание и ничего не изменится. Если мы говорим про бизнес-логику, то бизнес-логику Тепспек ещё, кстати, не уверен, что когда-то научится, но так у нас какая Какая-то проблема со связью, похоже. Сейчас попытаемся её решить.
Да, Андрей, ты пропадал?
>> А меня что-то выкинуло, но я вернулся.
>> Да, здорово. Итак, выкинул тебя про рассказывать про то, что в следующих генерациях тайспеки, возможно, появится.
>> Да, но пока нет. И так глубоко аналитики, к сожалению, пока не могут залезть вклад.
Ага. Давайте пойдём дальше. У нас прям опять вопрос от Антона. Антон у нас сегодня в ударе. А срез IP понятно. Что насчёт асинхронного взаимодействия? Кавка, Rabit и GPS.
>> Да. А ждал такого вопроса. А с GRPC, а если не ошибаюсь, TP работает, то есть они тоже позволяют генерировать клиента из сервера, если описывать GPC вот модельки в тепекформате с кавкой. Поддержки у них пока нет. То есть Openap есть там Streetlights и так далее. [фыркает] А, а в тапспеках ещё не завезли. А, но там можно их описать просто вот маркдаун страничкой рядышком. Это вот как раз у нас было, что контрактов у нас было немного синхронных, а вот кавки у нас прямо было много, и у нас прямо просто в папочке лежат отдельные файлики без влияния автодока. То есть пока, к сожалению, теспек только на росте, но тут как это сугубо личное мнение. Мне кажется, они смотрятся на Openна и тоже завезут что-то по типу стритлайта и так далее.
Угу. И ещё один вопрос от товарища Иванова. А можно ли чуть подробнее про кейс полиморфизмов, пожалуйста? Ты там жаловался на полиморфизм? Вот теперь тебя просят объяснить.
>> А, ну
>> у нас был в объединении у нас был сервис-аркестратор, который должен был при получении запросов раскидывать куски сообщения по разным сервисам. И, соответственно, из-за этого контракт, а, вот с той самой ручки, которая принимала все эти куски, он был, э, там были необязательные объекты. И, соответственно, полиморфизм заключался в том, что когда мы писали модельку, мы хотели их связать через конструкцию у any of. И вот как раз с генерацией офа упека были проблемы, то есть любой из уже четырёх представленных моделек, а из с конструкцией отпека были проблемы, то есть он упорно не хотел э генерировать в openпени off. И в Койле он тоже указывал либо все вместе, чтобы приходили, либо только один из представленных. То есть у него как раз он не совсем понимал, что любое количество из представленных экземпляров может приходить. Поэтому мы в итоге переработали и скрепя сердце продублировали вот эти куски в тепспеке. Но мы видели, что там был какой-то тикет как раз нао ситуацию. Ну, за развитием событий так и не доследили, так как сделали и классически уже забыли.
Вопросов у нас больше на сегодня нету. Итак, у нас на редкость сегодня были активные зрители и по обсуждениям, и по вопросам. Ну что ж, хочу поблагодарить Андрея за действительно интересный и злободневный доклад. Ещё раз хочу пригласить, у кого есть возможность прийти на квартирник и поделиться своими болями, рассказать о тех решениях в до коде, которые вы применяете, и просто сказать, возможно, свои истории за и против такого подхода. Это будет интересно. Квартирники всегда проходят у нас достаточно интересно на конференции КДФС. Ну и на сегодня мы тогда завершаем. До скорых встреч. Всем пока.
>> До свидания. Всё, завершили. Спасибо, Андрей. Прямо здорово. M.