День 2129. #Оффтоп
Почему Разработчики Любят Чистый Код, но Ненавидят Писать Документацию? Начало
В Developer Coefficient, исследовании, заказанном финтех-гигантом Stripe, разработчики сообщили, что они тратят более 17 часов в неделю на задачи по обслуживанию, такие как отладка и рефакторинг — работа, классифицируемая ими как «мытарство».
Опрос разработчиков 2024 на StackOverflow выявил множество тех же проблем и жалоб. Наибольшим разочарованием, с большим отрывом, был технический долг. И наоборот, больше всего разработчиков радовало улучшение качества их кода и среды разработки. И заглядывая в будущее, две области, в которых разработчики чувствовали, что они получат наибольшую выгоду от инструментов GenAI, — это тестирование и документирование.
В какой степени отличная документация помогает сократить «мытарства» и технический долг, которые приводят к разочарованию и выгоранию разработчиков? И в какой степени она может поддерживать то, что делает их счастливыми, например, качество кода?
Действительно ли документация помогает?
Есть эмпирические доказательства того, что хорошая документация оказывает положительное влияние на такие работы, как рефакторинг или отладка. Мета-исследование более 60 научных работ по качеству ПО и документации показало, что преимущества отражаются во многих аспектах: сокращение продолжительности задачи, улучшение качества кода, более высокая производительность и т.п. И исследования показывают, что документация часто занимает 11% рабочего времени разработчиков.
В исследовании PLOS ONE 2023 года была разработана модель для проверки того, какие методы окажут положительное или отрицательное влияние на процесс рефакторинга. Авторы пишут, что «документация помогает в адаптации новых членов команды и обеспечивает согласованность методов рефакторинга во всей команде».
Документация была особенно ценна при рефакторинге, предоставляя план, который экономит время и улучшает фокусировку. Исследователи обнаружили, что хорошая документация «гарантирует, что усилия по рефакторингу направлены на ощутимые и конкретные улучшения качества, максимизируя ценность каждого действия по рефакторингу и гарантируя долгосрочную поддерживаемость и развитие ПО».
Проблемы в поддержании эффективной документации
Почему же разработчики так часто считают документацию низкоприоритетной работой, которую они предпочли бы избегать, и писать вместо этого код?
В быстро меняющихся средах разработки поддержание актуальности документации может быть сложной задачей. Разработчики часто снижают приоритет документации из-за сжатых сроков и сосредоточенности на предоставлении рабочего кода. Это приводит к неформальной, сложной для понимания документации, которая быстро устаревает по мере развития ПО.
Ещё одна важная проблема - документация часто рассматривается как ненужные накладные расходы. Разработчики полагают, что код должен быть понятным сам по себе или что документация замедляет процесс разработки. Но это затрудняет онбординг новых членов команды и увеличивает время на задачи по обслуживанию из-за трат времени на понимание плохо документированного кода.
Устаревшая или недостаточная документация усугубляет технический долг. Поскольку кодовая база меняется, редко обновляемая документация может вводить в заблуждение, что приводит к ошибкам и неэффективным рабочим процессам, способствуя разочарованию и выгоранию.
Возникает новая дисциплина, «инженерия документации», которая пытается сблизить действия по написанию и кодированию, приводя работу по документированию кода в большее соответствие со стилем и целями инженерного отдела.
Чтобы документация не стала второстепенным элементом в жизненном цикле разработки, она должна быть наблюдаемой, чем-то, что можно измерить по ключевым показателям эффективности и целям, которые разработчики и их менеджеры часто используют при реализации проектов.
Окончание следует…
Источник: https://stackoverflow.blog/2024/11/11/developers-hate-documentation-ai-generated-toil-work/
Почему Разработчики Любят Чистый Код, но Ненавидят Писать Документацию? Начало
В Developer Coefficient, исследовании, заказанном финтех-гигантом Stripe, разработчики сообщили, что они тратят более 17 часов в неделю на задачи по обслуживанию, такие как отладка и рефакторинг — работа, классифицируемая ими как «мытарство».
Опрос разработчиков 2024 на StackOverflow выявил множество тех же проблем и жалоб. Наибольшим разочарованием, с большим отрывом, был технический долг. И наоборот, больше всего разработчиков радовало улучшение качества их кода и среды разработки. И заглядывая в будущее, две области, в которых разработчики чувствовали, что они получат наибольшую выгоду от инструментов GenAI, — это тестирование и документирование.
В какой степени отличная документация помогает сократить «мытарства» и технический долг, которые приводят к разочарованию и выгоранию разработчиков? И в какой степени она может поддерживать то, что делает их счастливыми, например, качество кода?
Действительно ли документация помогает?
Есть эмпирические доказательства того, что хорошая документация оказывает положительное влияние на такие работы, как рефакторинг или отладка. Мета-исследование более 60 научных работ по качеству ПО и документации показало, что преимущества отражаются во многих аспектах: сокращение продолжительности задачи, улучшение качества кода, более высокая производительность и т.п. И исследования показывают, что документация часто занимает 11% рабочего времени разработчиков.
В исследовании PLOS ONE 2023 года была разработана модель для проверки того, какие методы окажут положительное или отрицательное влияние на процесс рефакторинга. Авторы пишут, что «документация помогает в адаптации новых членов команды и обеспечивает согласованность методов рефакторинга во всей команде».
Документация была особенно ценна при рефакторинге, предоставляя план, который экономит время и улучшает фокусировку. Исследователи обнаружили, что хорошая документация «гарантирует, что усилия по рефакторингу направлены на ощутимые и конкретные улучшения качества, максимизируя ценность каждого действия по рефакторингу и гарантируя долгосрочную поддерживаемость и развитие ПО».
Проблемы в поддержании эффективной документации
Почему же разработчики так часто считают документацию низкоприоритетной работой, которую они предпочли бы избегать, и писать вместо этого код?
В быстро меняющихся средах разработки поддержание актуальности документации может быть сложной задачей. Разработчики часто снижают приоритет документации из-за сжатых сроков и сосредоточенности на предоставлении рабочего кода. Это приводит к неформальной, сложной для понимания документации, которая быстро устаревает по мере развития ПО.
Ещё одна важная проблема - документация часто рассматривается как ненужные накладные расходы. Разработчики полагают, что код должен быть понятным сам по себе или что документация замедляет процесс разработки. Но это затрудняет онбординг новых членов команды и увеличивает время на задачи по обслуживанию из-за трат времени на понимание плохо документированного кода.
Устаревшая или недостаточная документация усугубляет технический долг. Поскольку кодовая база меняется, редко обновляемая документация может вводить в заблуждение, что приводит к ошибкам и неэффективным рабочим процессам, способствуя разочарованию и выгоранию.
Возникает новая дисциплина, «инженерия документации», которая пытается сблизить действия по написанию и кодированию, приводя работу по документированию кода в большее соответствие со стилем и целями инженерного отдела.
Чтобы документация не стала второстепенным элементом в жизненном цикле разработки, она должна быть наблюдаемой, чем-то, что можно измерить по ключевым показателям эффективности и целям, которые разработчики и их менеджеры часто используют при реализации проектов.
Окончание следует…
Источник: https://stackoverflow.blog/2024/11/11/developers-hate-documentation-ai-generated-toil-work/
👍6
День 2130. #Оффтоп
Почему Разработчики Любят Чистый Код, но Ненавидят Писать Документацию? Окончание
Начало
Является ли документация, созданная ИИ, хорошим решением?
Существует несколько различных способов, которыми разработчик или команда разработчиков могут подойти к этой проблеме. В этом видео показано, как GitHub CoPilot работает как предиктивный движок, принимая подсказку от разработчика, а затем расширяя мысль и добавляя соответствующие детали.
Одним из ключевых элементов «мытарства» является нарушение состояния потока разработчика: ментальной зоны, где программисты наиболее продуктивны и креативны. Такие прерывания, как поиск недостающей документации или понимание запутанного кода, выводят разработчиков из потока, способствуя выгоранию и снижению удовлетворённости работой. Учитывая, насколько важна документация для сокращения технического долга и поддержания качества кода, автоматизация её создания является естественным решением.
Системы GenAI могут автоматически генерировать документацию либо в режиме реального времени, пока разработчик пишет код, либо после, просматривая кодовую базу. В то время как некоторые предлагают общие предложения на основе своих обучающих данных, другие настраиваются на вашу конкретную кодовую базу.
Переложив бремя создания документации на ИИ, разработчики могут сосредоточиться на задачах, которые им нравятся — разработке и решении проблем, — и при этом следить за тем, чтобы документация оставалась полной и актуальной.
Возможно, самое важное, что эта синергия между GenAI и разработчиками-людьми не устраняет человеческий надзор. Разработчики сохраняют контроль над результатом, направляя ИИ и проверяя точность вывода, что гарантирует соответствие конечного продукта их намерениям.
Лучшие практики для документации в Agile среде
Важно рассматривать эти инструменты как инструменты для внедрения новых лучших практик, которыми по-прежнему управляют люди, а не как роботов, которые выполняют всю работу самостоятельно.
Один из подходов заключается в использовании современных инструментов, которые автоматизируют поиск и создание документации. Инструменты, которые интегрируются со средой разработки, могут автоматически обновлять документацию по мере изменения кода, гарантируя, что она останется актуальной без необходимости значительных ручных усилий.
Другой вариант — внедрение исполняемой документации, которая развивается вместе с кодом. Сюда входят такие методы, как грамотное программирование или использование инструментов, которые генерируют документацию из комментариев и аннотаций кода. Встраивая документацию в сам код, разработчики могут гарантировать, что она останется синхронизированной с кодовой базой.
Принятие стратегии минимальной предварительной документации и подробной проектной документации впоследствии также может быть полезным. Это позволяет командам оставаться гибкими во время разработки, при этом сохраняя важную информацию для будущего использования. Такие практики поддерживают лучшую передачу знаний и помогают сократить труд, связанный с адаптацией и обслуживанием.
Используйте автоматизированный труд
Даже компании, ориентированные на ИИ, знают боль от устаревших документов. Но учитывая всех помощников в разработке кода, будущее, в котором код будет синхронизирован с документацией, вполне вероятно. Если ИИ может генерировать код, он может генерировать документы и поддерживать их в актуальном состоянии. Использование помощи ИИ для сокращения рутинной работы и повышения общего качества кода быстро становится ключевым навыком опытного разработчика.
Используя инструменты документации на основе ИИ, команды разработчиков могут сократить рутинную работу и уменьшить технический долг. Инженеры по документации или технические писатели будут выступать в качестве редакторов и распорядителей любой документации, созданной ИИ, предотвращая попадание ошибок или галлюцинаций в в остальном качественные документы.
Источник: https://stackoverflow.blog/2024/11/11/developers-hate-documentation-ai-generated-toil-work/
Почему Разработчики Любят Чистый Код, но Ненавидят Писать Документацию? Окончание
Начало
Является ли документация, созданная ИИ, хорошим решением?
Существует несколько различных способов, которыми разработчик или команда разработчиков могут подойти к этой проблеме. В этом видео показано, как GitHub CoPilot работает как предиктивный движок, принимая подсказку от разработчика, а затем расширяя мысль и добавляя соответствующие детали.
Одним из ключевых элементов «мытарства» является нарушение состояния потока разработчика: ментальной зоны, где программисты наиболее продуктивны и креативны. Такие прерывания, как поиск недостающей документации или понимание запутанного кода, выводят разработчиков из потока, способствуя выгоранию и снижению удовлетворённости работой. Учитывая, насколько важна документация для сокращения технического долга и поддержания качества кода, автоматизация её создания является естественным решением.
Системы GenAI могут автоматически генерировать документацию либо в режиме реального времени, пока разработчик пишет код, либо после, просматривая кодовую базу. В то время как некоторые предлагают общие предложения на основе своих обучающих данных, другие настраиваются на вашу конкретную кодовую базу.
Переложив бремя создания документации на ИИ, разработчики могут сосредоточиться на задачах, которые им нравятся — разработке и решении проблем, — и при этом следить за тем, чтобы документация оставалась полной и актуальной.
Возможно, самое важное, что эта синергия между GenAI и разработчиками-людьми не устраняет человеческий надзор. Разработчики сохраняют контроль над результатом, направляя ИИ и проверяя точность вывода, что гарантирует соответствие конечного продукта их намерениям.
Лучшие практики для документации в Agile среде
Важно рассматривать эти инструменты как инструменты для внедрения новых лучших практик, которыми по-прежнему управляют люди, а не как роботов, которые выполняют всю работу самостоятельно.
Один из подходов заключается в использовании современных инструментов, которые автоматизируют поиск и создание документации. Инструменты, которые интегрируются со средой разработки, могут автоматически обновлять документацию по мере изменения кода, гарантируя, что она останется актуальной без необходимости значительных ручных усилий.
Другой вариант — внедрение исполняемой документации, которая развивается вместе с кодом. Сюда входят такие методы, как грамотное программирование или использование инструментов, которые генерируют документацию из комментариев и аннотаций кода. Встраивая документацию в сам код, разработчики могут гарантировать, что она останется синхронизированной с кодовой базой.
Принятие стратегии минимальной предварительной документации и подробной проектной документации впоследствии также может быть полезным. Это позволяет командам оставаться гибкими во время разработки, при этом сохраняя важную информацию для будущего использования. Такие практики поддерживают лучшую передачу знаний и помогают сократить труд, связанный с адаптацией и обслуживанием.
Используйте автоматизированный труд
Даже компании, ориентированные на ИИ, знают боль от устаревших документов. Но учитывая всех помощников в разработке кода, будущее, в котором код будет синхронизирован с документацией, вполне вероятно. Если ИИ может генерировать код, он может генерировать документы и поддерживать их в актуальном состоянии. Использование помощи ИИ для сокращения рутинной работы и повышения общего качества кода быстро становится ключевым навыком опытного разработчика.
Используя инструменты документации на основе ИИ, команды разработчиков могут сократить рутинную работу и уменьшить технический долг. Инженеры по документации или технические писатели будут выступать в качестве редакторов и распорядителей любой документации, созданной ИИ, предотвращая попадание ошибок или галлюцинаций в в остальном качественные документы.
Источник: https://stackoverflow.blog/2024/11/11/developers-hate-documentation-ai-generated-toil-work/
👍4