Нужно ли писать документацию?
Статья написана по мотивам одноимённого доклада Семёна Факторовича на конференции SnowOne'23, адресованного студентам IT-специальностей. Если вы не очень любите читать и у вас есть 50 минут свободного времени, послушайте эту лекцию на Youtube.
Может ли IT-продукт жить без документации? Давайте попробуем разобраться на примере небольшого стартапа, команда которого разрабатывает новую инновационную систему защиты от киберугроз.
История 1: гениальный Олег и побег к лучшей жизни
Сначала был Олег, главный архитектор. Именно Олег с нуля создал архитектуру для проекта. Архитектура нигде не описана, но это и не нужно, ведь все сведения хранятся в самом надёжном месте — в голове у Олега.
Олег был настолько важен, что казалось, он будет в команде всегда. Но пришёл день, и Олег выгорел. Он решил, что станет свободным художником и укатит в Амстердам. Перед отъездом Олег собрал коллег и подробно объяснил устройство архитектуры. Все аплодировали: решения Олега были гениальны, безо всяких шуток.
Олега отпустили со спокойным сердцем, ведь он почти всегда оставлял комментарии в коде и очень подробно всем всё объяснил. Некоторые разработчики вдохновились примером Олега и тоже поехали в Амстердам. Команда стала немного меньше, потери предстояло восполнить.
Погоревали об Олеге и начали искать нового архитектора. Скоро нашёлся Дима и с энтузиазмом взялся за работу.
Диме пришлось собирать информацию о системе по частям, внимательно вычитывать код и часами общаться с разработчиками. Показания коллег местами расходились. В конце концов Дима разобрался, что именно делает каждая строчка кода, но не всегда понимал, почему Олег решал задачу именно так. Коллеги тоже не знали.
История 2: решительный Дима и онбординг новых сотрудников
Диме не понравились некоторые идеи Олега, которые всё равно никто не смог объяснить. К тому же у Димы были собственные идеи, поэтому он запланировал рефакторинг кода. Под эту задачу команда расширилась. Каждому из новичков Дима подробно объяснял: как реализована архитектура сейчас; какие изменения запланированы; почему именно такие. Со временем эта часть онбординга превратилась в бодрый трёхчасовой стендап, во время которого Дима думает: «Лучше бы я сейчас работал».
Дима понимает, что неплохо бы написать документ для онбординга. И архитектуру системы неплохо бы описать, чтобы не получилось, как с Олегом. Да и API надо бы задокументировать… Но времени на это у Димы не хватает.
История 3: Костя, который на это не подписывался
Костя — программист, и ему идея Димы с документацией нравится, но сам Костя не любит писать тексты на человеческом. Да и зачем ему? В последний раз он такое в дипломе писал, а потом только кодил. С чего вообще начинают писать документацию, с введения?
Иногда на Костю сваливается задача »опиши нам коротенечко новую фичу, тыжпрограммист, нам чисто для внутреннего пользования». Такие задачи Костю раздражают, но он честно открывает страницу внутренней Wiki и долго вымучивает из себя текст. Результат получается так себе, код Костя пишет намного быстрее и лучше.
Написать короткую статью на страницу или пофиксить двенадцать новых багов? Несложный выбор.
История 4: бесконечно выносливая Марина
Марина отвечает за техническую поддержку и отлично знает продукт. Она помогает пользователям разобраться с настройками и передаёт разработчикам найденные баги. В техподдержку пишут часто, но Марина очень продуктивная — успевает обработать все запросы за полдня.
Со временем система обрастает новыми фичами, добавляются новые сервисы, перепиливаются старые. Количество запросов увеличивается в геометрической прогрессии. Теперь Марина занята весь день, и у неё не хватает времени попить кофе.
Марина рассчитала: если дело так пойдёт и дальше, скоро придётся работать не по 8 часов в день, а по 19. Она просит нанять ей кого-нибудь в помощь. Требования к новичку скромные: ему предстоит просто копировать готовые ответы Марины, ведь многие вопросы пользователей повторяются.
История 5: проактивный Вадим и его эмпирические правила
Вадим — верховный менеджер. Он распределяет задачи между членами команды и следит за их выполнением. Не то чтобы Вадим против документации, просто он использует матрицу Эйзенхауэра, для него важно деплоить новые фичи. Документация для Вадима не в приоритете, её всё равно никто не читает. Да и непрофильная это активность для программистов — статейки писать.
Когда-то давно Вадим уже нанимал специалиста, который написал для команды пользовательскую документацию по ГОСТ, эта документация даже сохранилась. Вадим вспоминает закон Парето и убеждает себя, что какая-то документация значительно лучше, чем никакой. Даже если она в последний раз обновлялась при Медведеве, и в ней написано: «API-доки нет, но вы держитесь в любой непонятной ситуации пишите Марине».
История 6: код, текст и роботы
Доку писать никто не хотел, а технологическая сингулярность уже наступила. Поэтому к работе подключился Кинолай Оринов — человек и нейросеть. Кинолай генерил тексты намного быстрее Кости. «То, что надо!» — подумали все.
Правда чтобы Кинолай написал документацию для инновационной системы, надо Кинолаю сначала эту систему со всех сторон показать. Иными словами, придётся пустить чужой AI в свою проприетарную кодовую базу.
Такое решение сочли небезопасным: мало ли что у Кинолая на уме.
История 7:, а как могло бы быть?
Кажется, у команды скопились задачи, с которыми справится только один человек:
Что изменилось бы, если бы Даня включился в работу сразу?
Знания об архитектуре сохранились бы в документации и в Амстердам с Олегомне уехали. В любой команде есть текучка кадров, поэтому безопаснее, если важные знания сосредоточены не только в головах, но и в документах.
Диме, принявшему пост главного архитектора, такие документы очень бы пригодились. Документация надёжнее, чем код: Дима смог бы быстрее изучить устройство системы и разобраться в идеях Олега. Даже из самых подробных комментариев в коде Дима не понял бы, почему выбран именно такой технологический стек. А ещё при переносе идей из головы в код почти всегда возникают баги, а при переносе в документацию — как правило, нет.
Возможно, благодаря этим знаниям Дима отказался бы от рефакторинга.
Даня спроектировал бы внутреннюю базу знаний, разобравшись в потребностях команды. В базе знаний хранились бы и коротенечко описанные новые фичи, и онбординговые документы. Диме не пришлось бы становиться стендапером на полставки, а программисты вроде Кости со спокойной душой бы фиксили баги.
Внутренние документы здорово экономят время команды. База знаний, как единый источник информации — отличная альтернатива бесконечным вопросам в Slack про одно и то же. Сэкономленное время — это деньги, чему был бы очень рад менеджмент в лице Вадима.
Даня актуализировал и поддерживал бы пользовательскую документацию. Техподдержка в лице Марины сказала бы ему спасибо: дурацких вопросов стало бы меньше, и её рабочий день заканчивался бы вовремя.
Хорошая пользовательская документация значительно сокращает трудозатраты и снимает лишнюю нагрузку с техподдержки. Это порадовало бы и Вадима, потому что клонировать Марину оказалось дороговато.
А с Кинолаем Даня бы подружился, ведь с его помощью удалось бы автоматизировать часть работы. Правда заставить роботов писать документацию пока не получится.
Нейросети действительно уже научились писать связные тексты, но документация — это не просто текст. Чтобы написать этот текст, нужно знать не только саму предметную область, нужно также понимать контекст, аудиторию, её нужды и уровень. Возможно, однажды Кинолай научится и этому. Но к тому времени он заодно и код научится писать, и тогда всей команде можно будет ехать к Олегу в Амстердам.
Но это уже другая история.
Если вашему проекту жизненно необходима документация, приходите к нам в documentat.io. Мы разрабатываем техническую документацию на заказ и предоставляем техписателей на аутстаффинг. А ещё мы учим писать документацию — возможно, с помощью наших курсов вы сможете вырастить своего собственного Даню.
Автор текста: Ната Мелихова
Habrahabr.ru прочитано 2667 раз
