Разработчики не любят писать документы, какая альтернатива?
Я не часто провожу время на Reddit, в основном потому, что это отправляет вас в интернет-червоточину. Вы нажимаете на одну ссылку и вдруг понимаете, что потеряли полдня, крича на людей неправильно в Интернете. Однако я снисходительно отношусь к тому, чтобы читать r/ProgrammingHumor, и именно тогда я увидел это в начале недели.
Как бы вы ни старались, может быть трудно направить пользователей по правильному пути. Я признаю себя виновным здесь, поскольку я часто пропускаю все вводные видеоролики, экскурсии и мастера настройки. Однажды мне удалось удалить весь мой сайт только потому, что я слишком хотел попробовать новый инструмент. Сочетание чрезмерного рвения и высокомерия может быть разрушительной смесью.
К счастью, разработчики, как правило, предусмотрительны и действительно используют документацию. В опросе Stack Overflow 2018 г. 83% разработчиков заявили, что используют официальную документацию. Это даже выше, чем процент, который зависит от переполнения стека!
Если разработчики определенно используют и ценят документацию, что с ними делать, не желая документировать свой код? Я спросил несколько форумов как внутри AWS, так и у некоторых внешних сообществ сторонников разработчиков: Кто пишет документацию?
Оказывается, это все, кроме людей, которые пишут код для функций или API. Во многих местах работают технические писатели, в других — менеджеры по продукту, а в некоторых компаниях разработчики и группы внедрения пишут документацию. Кажется, все, кроме разработчиков.
Честно говоря, большая часть необходимой документации предназначена для конечных пользователей. Первый продукт, над которым я когда-либо работал, внутренняя система управления взаимоотношениями с клиентами (CRM), предназначалась для аудитории, которая определенно не была технической. Я был не только разработчиком, но и тестировщиком, системным администратором, администратором базы данных, менеджером по развертыванию и менеджером по продукту. Я также стал техническим писателем. Однако наличие приличных навыков письма означало, что часть документации была управляемой.
Документация по-прежнему непростая. Мне пришлось организовать этапы пути пользователя, чтобы настроить и начать работу в системе. Мне пришлось протестировать адаптацию и все пользовательские потоки, а затем пробежаться по каждой ключевой функции и сценарию, используя фиктивные данные, которые я ввел. Для каждого ключевого шага нужен скриншот. Иногда возникали странные ошибки, пограничные случаи и нестандартные ситуации, которые нужно было объяснить. Тогда и только тогда я действительно мог приступить к написанию, что само по себе требовало того, что я называл тремя «Ити»:
- Ясность. Легко ли понять используемые слова и фразы?
- Краткость. Написан ли текст лаконично, без лишних слов?
- Простота. Передает ли текст идею наиболее эффективным способом?
Даже с учетом этапа обеспечения качества (я подкупил одного из торговых представителей, чтобы просмотреть документацию), документация никогда не охватывала всего, что делают пользователи. Кто-то забывал сохранять изменения, кто-то вставлял информацию не в те поля. Затем один пользователь несколько раз случайно удалил все приложение со своего ноутбука.
Из-за важности документации для конечного пользователя всегда будет кто-то, кто сделает эту работу. Вероятно, наиболее важной функцией любого защитника разработчиков является создание контента, который является либо документацией, либо чем-то, что дополняет документацию, например демонстрациями, учебными пособиями, фрагментами кода, примерами API и семинарами. А когда документация неверна или устарела, они берутся за обновление материала.
Так кто же такие защитники разработчиков для инженеров внутри организации, пытающихся найти смысл в коде, который они не понимают?
Проблема с разработчиками, пишущими код, состоит из трех частей. Во-первых, написание документации — это навык, который разработчики редко удосуживаются приобрести или отточить. Во-вторых, в очереди приоритетов документация всегда находится в конце списка. Однако наиболее важной причиной является тот факт, что разработчики не заинтересованы в написании хорошей документации. Даже если им поручено создание документации, это не считается важной задачей. В конце концов, инженерам платят за доставку, а не за документацию.
Мы знаем, что кто-то пишет документацию, хотя и с перерывами. Документация часто становится клеевой работой, невидимой работой, которая необходима, но остается незамеченной. Часто кто-то в команде, наконец, не выдерживает неэффективности и берет на себя ответственность за написание документации.
Когда создается документация, мы знаем, что она ценна. Откуда нам знать? Когда разработчики, использующие документацию, громко жалуются на то, насколько она плоха или устарела. Затем цикл начинается снова с поиска другого клея, чтобы разозлиться и исправить документацию, без какой-либо славы, признания или очков для будущего продвижения по службе.
Каков ответ на заполнение пробела в документации для разработчиков? Вы могли бы подвергнуть их газлайтингу, так как начало этой презентации по избеганию документации предполагает:
Однако вы, вероятно, заботитесь о производительности доставки программного обеспечения и обеспечении продуктивности разработчиков. Вот четыре варианта предоставления разработчикам необходимой документации.
- Писать самодокументируемый код. Теоретически это хорошо, пока другим командам не понадобится использовать код напрямую или через API. Однако большая проблема заключается в том, что этот совет часто попадает в ту же категорию, что и стандарты кодирования. Все согласны, но никто не придерживается того, о чем договорились. Кроме того, между старшими и младшими разработчиками существуют очень разные степени навыков и различий в качестве и удобочитаемости кода.
- Оперативное документирование. Вместо того, чтобы отдельно заниматься кодированием и документацией, записывайте полезную информацию о коде во время его написания. Чаще всего это делается в комментариях, сообщениях коммитов, файлах readme и вики. Проблема в том, чтобы попытаться найти информацию и извлечь из нее что-то значимое. Помните, что большинство разработчиков пишут документацию со своей точки зрения, а не с точки зрения других.
- Документирование под руководством сообщества — это более совместный способ распространения работы над документацией. Форумы, вики, вопросы и ответы и приложения для обмена сообщениями являются наиболее распространенными инструментами, используемыми для расширения сотрудничества и участия. В некоторых случаях это хорошо работает, если культура ориентирована на обмен. Большинство крупных предприятий и в некоторых культурах испытывают настоящие проблемы с внедрением и опасаются публично ошибиться. Другим препятствием является проблема холодного запуска, которая замедляет развертывание этих платформ из-за отсутствия контента и пользователей.
- Документирование на основе ИИ — предыдущие три варианта по-прежнему полагаются на разработчиков, что является слабым звеном в написании полезной документации. Разработчики ненавидят писать документацию и не очень хороши в этом, так что, если мы исключим разработчиков из уравнения? За последние несколько лет ИИ добился значительных успехов в понимании семантического контекста языков. Те же алгоритмы можно настроить, чтобы применять ИИ для чтения и понимания кода. Это подход, который использует сингапурский стартап Quod AI, применяя свою технологию к размещенным в облаке и локальным кодовым базам, чтобы сделать код более быстрым для поиска, более простым для понимания его контекста и лучшим. при выявлении зависимостей в коде. Преимущество ИИ заключается в том, что он может искать код и артефакты кода в нескольких репозиториях и инструментах. Однако самым большим преимуществом является то, что ИИ не зависит от культуры и позволяет избежать проблемы с холодным запуском, поскольку ИИ генерирует документацию, как только он подключается к репозиторию.
Мы уже привыкли к тому, что ИИ справляется со многими обычными повседневными задачами. ИИ управляет большинством языковых переводов, механизмами рекомендаций и мобильными помощниками. Он даже справляется с некоторыми задачами вождения и системами автопилота авиакомпаний. Следующим шагом для ИИ является автоматизация многих утомительных задач, которые мешают разработчикам работать продуктивно. Следующим логическим шагом является замена человеческой документации на документацию, сгенерированную искусственным интеллектом, при необходимости с помощью разработчиков.
Как сегодня создается документация в вашей организации и кто пишет ее большую часть? Какими способами вы пытались побудить разработчиков внести свой вклад в документацию?
Мы помогаем ИТ-лидерам на предприятиях решать культурные проблемы, связанные с цифровой трансформацией, и переходить к культуре, основанной на сообществе, которая быстрее обеспечивает инновации и ценность для клиентов. Узнайте больше о нашей работе здесь.