Как стать автором
Обновить

Комментарии 17

Технический долг больная тема для разработчиков. Как показала практика, не каждый отличный разработчик может так же хорошо справляться и с документацией. И дело возможно сколько не в квалификации, а в психологии. На вопрос, почему этот момент не был отражен в документации, следует ответ от разработчика: «Ты же понимаешь, зачем это расписывать? Пара недель изучения и ты во всем разберешься». В компанию приходят люди с разной квалификацией, и далеко не всем может быть все понятно. Если вы заставите всех разработчиков помимо кода, писать и документацию, то вы в скором времени обнаружите, что качество такой документации оставляет желать лучшего. Потому что нужно учиться писать хорошую, лаконичную и понятную документацию на проект.
Как вариант неплохо работает следующая структура: каждый разработчик, на свой код тезисно пишет заметку. Далее, среди команды проекта выделяется один из разработчиков (назовем его — разработчик-тех.писатель), который может хорошо формулировать мысли и общаться с коллегами. Он собирает эти заметки и расписывает основные пункты, непонятные моменты восполняет путем общения с коллегами. В итоге формирует основной текст. Далее, итоговый текст передается техническому писателю, который по ГОСТ оформляет структуру добавляет дополнительные схемы, дополняет необходимой теорией, изменяет обороты речи. Технический писатель общается в основном только с разработчиком-тех.писатель, он же переводит ответ от разработчиков техническому писателю в понятный вид для читателя.
В итоге, вы не мучаете разработчиков не профильными задачами, и получаете качественную документацию.
Еще вариант решения такой проблема, это формирования привычки. В большинстве случаев в пятницу после обеда разработчики практически не работают. Это время можно регламентировать для написания технической документации, что было сделано за неделю. Но важно правильно это преподнести с точки зрения психологии. Разработчикам нужно не написать документацию, а оформить в виде текста свои достижения за неделю. И в начале обязательно отмечать лучших разработчиков за неделю, по той документации которую они написали, сделать как бы в духе соревнований.
Технический долг больная тема для разработчиков

Нет, если разработчик знает, как выстроен процесс и какая у него сфера ответственности за выдаваемый код. Если разработчик должен выдать документацию по настройкам написанного продукта, артефакты, рефлексию действий на сторонние системы и кейсы ошибок, то он заложит время и прекрасно это сделает. И не будет мучится и выдавать не пойми что. Заметки — сильно сказано, тут достаточно страницы в confluence, где аналитик сделает требования и кейсы, архитектор нарисует где и как это делать, разработчик дополнит данными по технике, тестировщик приложит чек лист проверки. И фича будет закрыта без лишней крови. И технического и иного долга не возникнет. Если конечно все кадры в процессе квалифицированы выполнять свою функцию, а не витают в облаках.

Далее, среди команды проекта выделяется один из разработчиков (назовем его — разработчик-тех.писатель), который может хорошо формулировать мысли и общаться с коллегами.

И вы получите чистой воды мисс-комм, потому что сами пишите, что «В компанию приходят люди с разной квалификацией, и далеко не всем может быть все понятно». Далее, то что он напишет, будет искажено. Потом у вас в цепочке тех.писатель, который также исказит. На выходе будет ну вообще ни секунды не качественная документация.

Он собирает эти заметки и расписывает основные пункты, непонятные моменты восполняет путем общения с коллегами

И коллеги быстро начинают его ненавидеть)))

В большинстве случаев в пятницу после обеда разработчики практически не работают. Это время можно регламентировать для написания технической документации, что было сделано за неделю.

А если разработчик поймал flow, ему надо оторваться?
И тем более, раз «разработчики практически не работают», то почему они должны работать над документацией?)))
Это может быть однократное мероприятие, но системно — будут отписки.

Да, хорошо выстроенный процесс-это гарантия успеха и понятной документации. То, что вы описали присутствует в нашей компании. Системный аналитик пишет бизнес-системный требования по разработанному функционалу, разработчик дополняет техническими нюансами для программистов и документ готов. Действиьельно, просить от разработчика полную документацию несколько странно, но просить часть такого как бы reade me на разработанный функционал вполне нормально, особенно если из непривычного конфлюенсе мы перевели часть документации в гит в markdown (это более привлекательный формат для разработчиков)

Но если фичу срочно нужно было в продакшен без документации, то после у каждой роли появляется своя часть техдолга документации.

Нет, если разработчик знает, как выстроен процесс и какая у него сфера ответственности за выдаваемый код. Если разработчик должен выдать документацию по настройкам написанного продукта, артефакты, рефлексию действий на сторонние системы и кейсы ошибок, то он заложит время и прекрасно это сделает.

Ключевое слово «если», вы наверное никогда не были разработчиком и никогда с ними не работали, или живете на какой то другой планете. Вы много можете перечислить таких компаний, где все работает именно так хорошо как вы описали? Я к сожалению, вот ни одной.
Потом у вас в цепочке тех.писатель, который также исказит. На выходе будет ну вообще ни секунды не качественная документация.
— бред полный. Во всем западном мире ИТ компаний, технический писатель вещь обязательная, а у вас появляются какие то «искажения». Я работал с техническим писателем в крупной питерской ИТ компании, и все было отлично, никаких искажений.
И коллеги быстро начинают его ненавидеть)))

Как раз таки наоборот, ему в отличие от технического писателя не требуется все досконально рассказывать. Понимает все с полуслова, эконом время разработчикам, и не требует от них оформлять это письменно.
Хотел развернуто ответить вам, но потом почитал ваш блог и ваши другие комментарии и ну вот вообще не хочется обсуждать что-то с таким непрофессионалом. Простите, но не пишите больше никогда нигде, где присутствую я. Или выучите матчасть, что такое ИТ, как функционирует разработка, что такое софт и железо. Спасибо.
Хотел развернуто ответить вам

— Так надо было. Переходите на личности, когда нечего ответить?
Простите, но не пишите больше никогда нигде, где присутствую я

— а еще не играйте в мои игрушки. Просто детский сад. Я Вас в комментариях к своим постам ОЧЕНЬ ЖДУ. Самое большое благо для меня это критика настоящих профессионалов. Скоро будет интересный пост про разработку от меня, обязательно пришлю Вам ссылку, в комментарии Welcome.
выучите матчасть, что такое ИТ, как функционирует разработка, что такое софт и железо.

— воздух сотрясать и я могу. Так же могу себе в профиле Хабра написать что я «римский папа», но от этого я лучше не стану, и им тоже. Вы делом можете подтвердить свою квалификацию? Напишите хоть один серьезный профессиональный пост, раз в этом Вы так хорошо разбираетесь. Оценим Ваш профессиональный уровень до достоинству. Опубликуйте проект на Github. А так, с вашей стороны пока только громкие заявления без дела.

Разработчики проходят ревью и есть гайды, по которым это делается один из пунктов это наличие документации от разработчиков. Это технический документ, который не сможет описать никто кроме разработчика. Как правило раньше не было такой документации и многие ковырялись в коде разбирая его, но сейчас это правило внедрили и в каждую разработку закладывается время на документацию, менеджеры понимают зачем это и почему это важно.

Но большинство документации конечно пишет системный аналитик, поэтому от небольшого кол-ва разработчики не страдают

Срочная фича в прод - это проблема менеджмента и планирования, но никак не технической команды. В этом случае команда консолидировано посылает менеджера... на перепланирование сроков по фиче))

Потому что сбор шишек и плюшек - это задача именно менеджмента и нельзя, чтобы они фокусировались только на втором, не получая первого.

Насчёт документации от разработки - существуют инструменты для ее автоматической генерации на основе кода/комментариев. Посмотрите в сторону таких продуктов - сильно сокращает время на документирование. И последующий разбор ошибок кстати тоже так как трассирует все цепочки вызовов с данными

Да мы смотрим в сторону автоматизации сбора документации. Сейчас уже так реализована генерация свагера для сервиса, следующий этап посмотреть в сторону разбора этого свагера на документацию (примеры запрос-ответ, вх-вых параметры сервиса).
Срочная фича в прод — это проблема менеджмента и планирования, но никак не технической команды.

Отчасти вы правы, но мы команда вместо с менеджерами и иногда срочная фича важнее в прод, чем документация до разработки, поэтому мы ищем компромисс. Но стараемся таких ситуаций не допускать.
Как то в посте пропустили в какой системе пишется документация. Какую корпоративную Wiki используете, или какое то другое решение используете? В структуре документации какого стандарта придерживаетесь(ГОСТ, ISO)?
devzona возможно сделаем статью по теме документации подробнее.
Если коротко, то у нас Confluence и Git в нотации AsciiDoc или Markdown. Придерживаемся внутренних стандартов, которые получились на основе практики и удобства.
Очень странно, что у вас у аналитиков вообще присутствует такая вещь, как долг в любом виде.

Разработчики пишут код со слов, тестирование тестирует со слов, а бизнес думал, что его слова по-другому поняли.

Без внятного описания сопровождение, особенно в банковской сфере, просто не возьмет функционал на установку. Разработчик без ФТ/БФТ/US или иного законченного описания также не возьмет фичу на реализацию — по крайней мере я в свою разработку без полной проработки процесса не пускаю — в любой парадигме разработка начинается с законченных требований. Может быть не полных, не финальных, но законченных, а не по принципу «лишь бы ввязаться»
Без тест-кейсов тестирование не возьмет в работу — первый вопрос любого тестера «а как тут работать».
Как то все перекручено с ног на голову.

Далее тезис
Поддержка просит разобраться в дефекте, разработчик в отпуске,

Простите, но это как? Один разработчик на фичу? А тим.лиды/тех.лиды?

Плюс, извините, но технический долг — это когда разработчик сделал абы как, с условием дальнейшей переделки. У аналитиков это называется — неполное соответствие занимаемой должности.

Могут быть разные причины почему не написана или неактуальна документация:

1) команда разросталась не равномерно, сначала приходили разработчики, потом аналитики. Не было ресурсов писать аналитик сначала до разработки

2) сроки могли быть настолько сжатыми, что аналитик формулировка минимально достаточные требования, чтобы разработчик делал фичу в задаче, тестер потом тестировал, а документацию дописывал после выката в продакшен. Ведь бизнесу важнее принесенная ценность в продакшен, чем полностью описанная документация.

Да, минимальное описание всегда присутствует, но у системных аналитиков есть внутренние стандарты, количество и качество документации на фичу, чтобы по ней не было техдолга. И к сожалению, не всегда хватает ресурсов, так как кол-во аналитков в команде ограничено.

Согласна с вами, без минимальных требований разработчик не начнет зазадачу, но тут добавлю все зависит от уровня разработчика, некоторые могут взять задачу, придумать и реализовать после небольшой груминг встречи. Также в банке есть функционал, который разрабатывался без аналитики, его постепенно как раз описывают, это тоже тех.долг.

Некоторые решения знает только один разработчик, стараемся такого не допускать, то есть Лиды погружаются во все, а также есть заменяемость, но редкие случаи бывают, что без документации не разберешься, если этот один разработчик в отпуске

Это понятно, просто после статьи остаётся несколько другое впечатление, поэтому я поднял штандарт на защиту обездоленных)))

А ещё отсутствие документации и обход процессов — это уязвимости внутренних векторов атак.
И та вещь, которая, по хорошему, не должна происходить в банках, работающих с одним из самых чувствительных типов ПД, не считая денег.

Разработческий техдолг — это временный риск. Аналитический техдолг — это RCE.
WillDrug разработка выполняется со всеми уровнями защиты, есть общие документы описывающие какими должны быть банковские решения с точки зрения надежности и защищенности, отсутствие документации не делает разработку уязвимой. Отсутствие документации делаем более сложным доработки и анализ дефектов, если такое случается, как и отмечено в статье
Есть описания как надо, но никто не написал как должно быть сделано и никто не знает, как в итоге сделали.
Не проверенное на соответствие стандартам решение, написанное разработчиком Н. Может быть, он сениор и написал даже лучше, чем требуют стандарты. Может быть, он джуниор и допустил 20 ошибок от которых потом майнеры на транзакционных серверах заводятся.
А может быть, он уже обновил загранпаспорт и скоро сбежит с парочкой миллионов, добавив обфусцированный бэкдор

Более всего вероятно то, что все будет окей, как обычно. Решение будет окей или никто не заметит уязвимости. Однако риск повышается, куда ни плюнь
Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.