Comments 17
Как вариант неплохо работает следующая структура: каждый разработчик, на свой код тезисно пишет заметку. Далее, среди команды проекта выделяется один из разработчиков (назовем его — разработчик-тех.писатель), который может хорошо формулировать мысли и общаться с коллегами. Он собирает эти заметки и расписывает основные пункты, непонятные моменты восполняет путем общения с коллегами. В итоге формирует основной текст. Далее, итоговый текст передается техническому писателю, который по ГОСТ оформляет структуру добавляет дополнительные схемы, дополняет необходимой теорией, изменяет обороты речи. Технический писатель общается в основном только с разработчиком-тех.писатель, он же переводит ответ от разработчиков техническому писателю в понятный вид для читателя.
В итоге, вы не мучаете разработчиков не профильными задачами, и получаете качественную документацию.
Еще вариант решения такой проблема, это формирования привычки. В большинстве случаев в пятницу после обеда разработчики практически не работают. Это время можно регламентировать для написания технической документации, что было сделано за неделю. Но важно правильно это преподнести с точки зрения психологии. Разработчикам нужно не написать документацию, а оформить в виде текста свои достижения за неделю. И в начале обязательно отмечать лучших разработчиков за неделю, по той документации которую они написали, сделать как бы в духе соревнований.
Да, хорошо выстроенный процесс-это гарантия успеха и понятной документации. То, что вы описали присутствует в нашей компании. Системный аналитик пишет бизнес-системный требования по разработанному функционалу, разработчик дополняет техническими нюансами для программистов и документ готов. Действиьельно, просить от разработчика полную документацию несколько странно, но просить часть такого как бы reade me на разработанный функционал вполне нормально, особенно если из непривычного конфлюенсе мы перевели часть документации в гит в markdown (это более привлекательный формат для разработчиков)
Но если фичу срочно нужно было в продакшен без документации, то после у каждой роли появляется своя часть техдолга документации.
Нет, если разработчик знает, как выстроен процесс и какая у него сфера ответственности за выдаваемый код. Если разработчик должен выдать документацию по настройкам написанного продукта, артефакты, рефлексию действий на сторонние системы и кейсы ошибок, то он заложит время и прекрасно это сделает.
Ключевое слово «если», вы наверное никогда не были разработчиком и никогда с ними не работали, или живете на какой то другой планете. Вы много можете перечислить таких компаний, где все работает именно так хорошо как вы описали? Я к сожалению, вот ни одной.
Потом у вас в цепочке тех.писатель, который также исказит. На выходе будет ну вообще ни секунды не качественная документация.— бред полный. Во всем западном мире ИТ компаний, технический писатель вещь обязательная, а у вас появляются какие то «искажения». Я работал с техническим писателем в крупной питерской ИТ компании, и все было отлично, никаких искажений.
И коллеги быстро начинают его ненавидеть)))
Как раз таки наоборот, ему в отличие от технического писателя не требуется все досконально рассказывать. Понимает все с полуслова, эконом время разработчикам, и не требует от них оформлять это письменно.
Хотел развернуто ответить вам
— Так надо было. Переходите на личности, когда нечего ответить?
Простите, но не пишите больше никогда нигде, где присутствую я
— а еще не играйте в мои игрушки. Просто детский сад. Я Вас в комментариях к своим постам ОЧЕНЬ ЖДУ. Самое большое благо для меня это критика настоящих профессионалов. Скоро будет интересный пост про разработку от меня, обязательно пришлю Вам ссылку, в комментарии Welcome.
выучите матчасть, что такое ИТ, как функционирует разработка, что такое софт и железо.
— воздух сотрясать и я могу. Так же могу себе в профиле Хабра написать что я «римский папа», но от этого я лучше не стану, и им тоже. Вы делом можете подтвердить свою квалификацию? Напишите хоть один серьезный профессиональный пост, раз в этом Вы так хорошо разбираетесь. Оценим Ваш профессиональный уровень до достоинству. Опубликуйте проект на Github. А так, с вашей стороны пока только громкие заявления без дела.
Разработчики проходят ревью и есть гайды, по которым это делается один из пунктов это наличие документации от разработчиков. Это технический документ, который не сможет описать никто кроме разработчика. Как правило раньше не было такой документации и многие ковырялись в коде разбирая его, но сейчас это правило внедрили и в каждую разработку закладывается время на документацию, менеджеры понимают зачем это и почему это важно.
Но большинство документации конечно пишет системный аналитик, поэтому от небольшого кол-ва разработчики не страдают
Срочная фича в прод — это проблема менеджмента и планирования, но никак не технической команды.
Отчасти вы правы, но мы команда вместо с менеджерами и иногда срочная фича важнее в прод, чем документация до разработки, поэтому мы ищем компромисс. Но стараемся таких ситуаций не допускать.
Если коротко, то у нас Confluence и Git в нотации AsciiDoc или Markdown. Придерживаемся внутренних стандартов, которые получились на основе практики и удобства.
Могут быть разные причины почему не написана или неактуальна документация:
1) команда разросталась не равномерно, сначала приходили разработчики, потом аналитики. Не было ресурсов писать аналитик сначала до разработки
2) сроки могли быть настолько сжатыми, что аналитик формулировка минимально достаточные требования, чтобы разработчик делал фичу в задаче, тестер потом тестировал, а документацию дописывал после выката в продакшен. Ведь бизнесу важнее принесенная ценность в продакшен, чем полностью описанная документация.
Да, минимальное описание всегда присутствует, но у системных аналитиков есть внутренние стандарты, количество и качество документации на фичу, чтобы по ней не было техдолга. И к сожалению, не всегда хватает ресурсов, так как кол-во аналитков в команде ограничено.
Согласна с вами, без минимальных требований разработчик не начнет зазадачу, но тут добавлю все зависит от уровня разработчика, некоторые могут взять задачу, придумать и реализовать после небольшой груминг встречи. Также в банке есть функционал, который разрабатывался без аналитики, его постепенно как раз описывают, это тоже тех.долг.
Некоторые решения знает только один разработчик, стараемся такого не допускать, то есть Лиды погружаются во все, а также есть заменяемость, но редкие случаи бывают, что без документации не разберешься, если этот один разработчик в отпуске
И та вещь, которая, по хорошему, не должна происходить в банках, работающих с одним из самых чувствительных типов ПД, не считая денег.
Разработческий техдолг — это временный риск. Аналитический техдолг — это RCE.
Не проверенное на соответствие стандартам решение, написанное разработчиком Н. Может быть, он сениор и написал даже лучше, чем требуют стандарты. Может быть, он джуниор и допустил 20 ошибок от которых потом майнеры на транзакционных серверах заводятся.
А может быть, он уже обновил загранпаспорт и скоро сбежит с парочкой миллионов, добавив обфусцированный бэкдор
Более всего вероятно то, что все будет окей, как обычно. Решение будет окей или никто не заметит уязвимости. Однако риск повышается, куда ни плюнь
Техдолг — нельзя копить, закрывать