Обсуждения неудачных примеров README-файлов и документации — одна из популярных тем на профильных площадках и форумах [вкупе с другими «вечнозелеными» спорами в ИТ]. Сегодня мы в Beeline Cloud решили посмотреть, что думают о проблеме плохой документации разработчики и ученые, может ли ИИ улучшить ситуацию, что такое «нейросетевой ридмитит» — и как можно «доработать напильником» сгенерированные спеки и инструкции.
(Не)понятные спеки
Метаанализ 60 научных работ, проведенный специалистами из Турции и Канады и посвященный качеству ПО показал, что наличие хорошей документации положительно влияет сразу на несколько аспектов разработки: сокращает время выполнения задач, повышает качество кода, увеличивает продуктивность в команде — во многом потому, что на работу с документацией у программистов уходит порядка 11% времени. Авторы уже другого исследования, опубликованного в журнале PLOS One в 2023 году, попытались определить, какие практики оказывают положительное или отрицательное влияние на процесс рефакторинга. Они отмечают, что документация играет ключевую роль: она упрощает онбординг новых участников команды и помогает сохранять единый подход к рефакторингу.
Как говорил — хотя и немного высокопарно — соучредитель Stack Overflow Джоэл Спольски:
«Документация содержит мудрость поколений, которая простирается за пределы обычной спецификации разработанного продукта»
И действительно, документация для библиотек или фреймворков нередко становится источником лучших практик для начинающих, помогает быстрее освоить новые инструменты. По данным опроса Stack Overflow за прошлый год, охватившего около 50 тыс. разработчиков, 68% из них обращались к документации при изучении новых языков или технологий.
В условиях быстрого цикла разработки поддерживать документацию в актуальном состоянии бывает непросто — и команды нередко отодвигают эту задачу на второй план. Со временем она имеет тенденцию становиться фрагментарной и сложной для восприятия, а по мере развития продукта еще и быстро устаревает. Очевидно, что неполная документация создает проблемы для потенциальных пользователей программного обеспечения. Например, если она содержит устаревшие функции, пользователь оказывается в ситуации, когда ему приходится методом тыка разбираться, как все работает на самом деле, и гадать, не наткнулся ли он на недокументированную возможность, которую уже нельзя (или еще нельзя) использовать. Как пишет разработчик DHIS2, опенсорсной платформы для сбора и визуализации данных: «Встретив недокументированную функцию, разработчик вынужден взвешивать все риски, ведь в следующей версии ПО она может просто-напросто сломаться».
Без подробной документации страдают не только пользователи — разработчики тоже теряют контроль над собственным продуктом, ведь неполнота спецификации усугубляет ситуацию с техническим долгом. Ведущий QA-инженер Кристин Джеквони в своем блоге описала показательный случай, когда ей пришлось тестировать новую реализацию системы с десятками тест-кейсов практически вслепую — ни одна из функций не была задокументирована: «Мне приходилось строить догадки, заваливать вопросами продакт-менеджера. Более того, вскоре после релиза выяснилось, что мы не реализовали один важный параметр конфигурации — не реализовали, потому что не знали о его существовании».
Что интересно, существуют исследования, которые показывают, что профессионалы и не профессионалы испытывают схожие сложности при чтении разного рода спецификаций (иными словами: дело не в том, что новички «непонятливые»). Еще в 2015 году исследователи из Макгиллского университета в Канаде изучали часто встречающиеся проблемы в API-документации и то, какой эффект они оказывают на разработку и использование программных продуктов. В рамках исследования они опросили порядка трехсот сотрудников компании IBM со стажем от 1 до 40 лет (в выборку попали как разработчики, архитекторы и тестировщики, так и нетехнические специалисты вроде консультантов и менеджеров) и попросили их предоставить примеры плохой и хорошей технической документации — и рассказать, чем обосновано их мнение о ее качестве. Участники были вольны выбирать материалы из разных источников — публичных и внутренних корпоративных, а также open source-проектов.
Результат показал, что независимо от уровня технической подготовки респонденты выделили похожие проблемы: расплывчатые формулировки, поверхностные либо вовсе отсутствующие примеры. Также были претензии к структуре и читаемости: опрошенные жаловались на громоздкие описания и разбитые на несколько страниц объяснения одного термина.
Документация, которая умеет делать больно
В обсуждениях на форумах и в персональных блогах разработчиков можно найти большое количество примеров того, как не нужно составлять документацию — и что получается, если не уделять ей должного внимания. В качестве антипримера в одном из обсуждений на Reddit отметили XML-стандарт DITA, что иронично, предназначенный для создания и публикации технической документации: «Похоже, что его писал человек, который живет DITA и настолько увлечен проектом, что больше не способен нормально контактировать с другими людьми». Действительно, фрагменты документации страдают от избыточных повторов и витиеватых формулировок — язык настолько усложнен, что чтение текста вызывает физическую боль:
«Если использовать механизм conref — при условии, что адресуемый элемент имеет тот же тип, что и элемент, содержащий ссылку, а список доменов атрибута domains исходной темы совпадает со списком доменов в документе со ссылкой либо является его подмножеством, набор допустимых элементов в исходном элементе гарантированно будет таким же или более ограниченным, чем в элементе, который на него ссылается»
Частая история, когда разработчики, глубоко погруженные в техническую область, стараются максимально точно передать информацию и теряют из виду важный нюанс: точность сама по себе еще не делает документацию полезной для читателя. Так, в качестве контрпримера для DITA часто приводят AsciiDoc: материал технический, однако написан значительно более доступным языком — с понятными инструкциями, примерами и предупреждениями, которые доступны даже специалистам, только начинающим знакомство со стандартом.
В качестве еще одного примера не самой удачной документации часто приводят Android SDK, где наблюдается немного другая проблема. Там используются слишком абстрактные формулировки, а еще бывают опущены единицы измерения в описаниях функций, задающих размеры шрифтов — setFontSize(float): sets the font size. Один из участников профильного треда заметил, что здесь пришлась бы к месту недооцененная венгерская нотация: «Конечно, с ней можно и переборщить, но duration_ms, response.size_bytes, max_memory_mb или overhead_ns было бы гораздо проще использовать». Подобные вещи заставляют проделывать дополнительную работу; многие разработчики отмечают, что им приходится «выпадать» из состояния потока в попытке разобраться, что вообще происходит и какой корректный параметр ожидает функция.
Помогут нейросети — но есть нюансы
С одной стороны, значительная часть документации сегодня уже генерируется с помощью систем ИИ. Это — одна из задач, с которой нейросети справляются довольно сносно, даже хорошо. В 2024 году индийские исследователи, среди которых был разработчик из Amazon, дообучили GPT-2 и RoBERTa на Python-датасете из CodeSearchNet Challenge с GitHub — это примерно 2 млн строк кода и комментариев к нему — а затем сравнили, насколько точно описания в сгенерированных ими документациях соответствуют действительности. Результат менялся от модели к модели, но лучшие представители генерировали достойно оформленную документацию в 99,94% случаев — ее оставалось лишь точечно «отшлифовать».
Большое количество подобных профильных инструментов можно найти на GitHub. Например, DocAgent и RepoAgent способны обновлять и актуализировать документацию на лету. Отдельное направление — генерация документации для легаси, где ручное описание часто занимает много времени в условиях, когда авторы оригинального кода давно покинули компанию, а сам код усложнен многочисленными изменениями и доработками.
Однако системы ИИ сложно назвать «серебряной пулей». Документация, написанная нейросетью без должного контроля, бывает, получается слишком общей и «водянистой». Некоторые участники исследования, которое проводили специалисты из Макгиллского университета, отмечали эту проблему, когда подбирали примеры неудачной документации: «Мне часто приходится иметь дело со сгенерированной документацией, в которой не описаны многие классы и методы». Веб-дизайнер и автор профильных книг и учебных курсов Скотт Райли считает, что качество автоматически сформированных материалов почти всегда уступает текстам, написанным человеком: «Отличная документация появляется тогда, когда человек активно анализирует правила и ограничения, тщательно обдумывает формулировки».
Даже если интеллектуальной системе удается сгенерировать достойную по содержанию документацию, нет гарантии, что она будет понятна и удобна для восприятия. И поскольку генерируемый системой ИИ результат часто непредсказуемый, необходим технический писатель или редактор для проверки содержания и стиля текста.
Так, сгенерированную документацию ругают за ридмитит — избыток клише и ошибок, которые часто проявляются в README-файлах. Латинизмы, обилие аббревиатур, чрезмерно неформальный стиль — где-то под всем этим оказывается погребены полезные инструкции. Системные промпты могут частично исправить ситуацию, однако, как говорят специалисты, навязать нейросети строгий стиль сложнее, чем кажется [почти так же сложно, как убедить ее перестать говорить о гоблинах и гремлинах].
К сожалению, и документация, написанная «вручную», необязательно будет лишена этих минусов: в ИТ-сообществе в качестве неудачного примера приводят документацию MSDN — она перегружена гиперссылками, а разбор одной команды может быть разбросан по разным страницам. Другим антипримером называют документацию .NET, которая имеет те же самые недостатки. В одном из тредов на Reddit пользователь пишет: «Практически все, что касается документации в C#, за исключением тривиальных вещей, кажется абстрактным и неудобным в работе. И в половине случаев ответом может оказаться пост на Stack Overflow, содержащий неработающие ссылки на заброшенный блог».
Вероятно, наиболее эффективным способом к составлению документации окажется гибридный подход, когда системы ИИ используются для того, чтобы структурировать мысли разработчика и сделать их легко усваиваемыми для читателя, а затем документ аккуратно доводится до приемлемого вида специалистом — уточняются формулировки, добавляется контекст. Иными словами, ИИ может заметно ускорить подготовку базы, но финальное качество по-прежнему во многом зависит от человека. Посмотрим на несколько рекомендаций по «ручному» улучшению документации, которые дают участники ИТ-сообщества.
Пара рецептов
Среди не самых очевидных рекомендаций встречаются советы о том, каких формулировок в документации лучше избегать. Так, в британской компании Consonance, разрабатывающей софт для издательской индустрии, считают, что авторам стоит осторожнее использовать снисходительные обороты и слова вроде «легко» (easy), «безболезненно» (painless), «тривиально» (trivial), «просто» (simple), «всего лишь» (just). Проблема в том, что разработчики, подготавливая документацию и опираясь на собственный опыт, нередко воспринимают отдельные шаги как очевидные и потому могут недостаточно подробно их объяснять. Подобные формулировки становятся своеобразным оправданием, позволяющим не углубляться в детали там, где читателю как раз нужны пояснения. По мнению специалистов Consonance, отказ от таких конструкций может, с одной стороны, сделать документацию более комфортной для чтения. А с другой — поможет авторам избежать предвзятых оценок и, как следствие, слишком туманных описаний и «перепрыгивания» через важные разделы документа.
Чтобы отследить недостаток деталей, также имеет смысл проводить юзабилити-тестирование готовой документации: по возможности привлечь коллег из смежных отделов и попросить их выполнить описанные инструкции на «чистой» машине, где рабочая среда не была настроена заранее. Этот шаг нужен, чтобы выявить скрытые допущения: например, инструкция может неявно предполагать, что определенная библиотека уже установлена по умолчанию, хотя ее может не быть у пользователя, который впервые решил настроить условный фреймворк. Подобная проверка может быть довольно хлопотной, но позволит понять, какие шаги описаны недостаточно прозрачно, где не хватает уточнений и какие места стоит доработать.
Beeline Cloud — безопасный облачный провайдер. Разрабатываем облачные решения, чтобы вы предоставляли клиентам лучшие сервисы.
Дополнительное чтение на Хабре и нашей DIY-площадке «вАЙТИ»: