Как стать автором
Обновить
129.92

Нужно ли писать документацию?

Уровень сложностиПростой
Время на прочтение5 мин
Количество просмотров5.4K

Статья написана по мотивам одноимённого доклада Семёна Факторовича на конференции SnowOne'23, адресованного студентам IT-специальностей. Если вы не очень любите читать и у вас есть 50 минут свободного времени, послушайте эту лекцию на Youtube.

Может ли IT-продукт жить без документации? Давайте попробуем разобраться на примере небольшого стартапа, команда которого разрабатывает новую инновационную систему защиты от киберугроз.

История 1: гениальный Олег и побег к лучшей жизни 

Сначала был Олег, главный архитектор. Именно Олег с нуля создал архитектуру для проекта. Архитектура нигде не описана, но это и не нужно, ведь все сведения хранятся в самом надёжном месте — в голове у Олега.

Олег был настолько важен, что казалось, он будет в команде всегда. Но пришёл день, и Олег выгорел. Он решил, что станет свободным художником и укатит в Амстердам. Перед отъездом Олег собрал коллег и подробно объяснил устройство архитектуры. Все аплодировали: решения Олега были гениальны, безо всяких шуток.

Олега отпустили со спокойным сердцем, ведь он почти всегда оставлял комментарии в коде и очень подробно всем всё объяснил. Некоторые разработчики вдохновились примером Олега и тоже поехали в Амстердам. Команда стала немного меньше, потери предстояло восполнить.

Погоревали об Олеге и начали искать нового архитектора. Скоро нашёлся Дима и с энтузиазмом взялся за работу.

Диме пришлось собирать информацию о системе по частям, внимательно вычитывать код и часами общаться с разработчиками. Показания коллег местами расходились. В конце концов Дима разобрался, что именно делает каждая строчка кода, но не всегда понимал, почему Олег решал задачу именно так. Коллеги тоже не знали.

История 2: решительный Дима и онбординг новых сотрудников

Диме не понравились некоторые идеи Олега, которые всё равно никто не смог объяснить. К тому же у Димы были собственные идеи, поэтому он запланировал рефакторинг кода. Под эту задачу команда расширилась. Каждому из новичков Дима подробно объяснял: как реализована архитектура сейчас; какие изменения запланированы; почему именно такие. Со временем эта часть онбординга превратилась в бодрый трёхчасовой стендап, во время которого Дима думает: «Лучше бы я сейчас работал».

Дима понимает, что неплохо бы написать документ для онбординга. И архитектуру системы неплохо бы описать, чтобы не получилось, как с Олегом. Да и API надо бы задокументировать… Но времени на это у Димы не хватает.

История 3: Костя, который на это не подписывался

Костя — программист, и ему идея Димы с документацией нравится, но сам Костя не любит писать тексты на человеческом. Да и зачем ему? В последний раз он такое в дипломе писал, а потом только кодил. С чего вообще начинают писать документацию, с введения?

Иногда на Костю сваливается задача «опиши нам коротенечко новую фичу, тыжпрограммист, нам чисто для внутреннего пользования». Такие задачи Костю раздражают, но он честно открывает страницу внутренней Wiki и долго вымучивает из себя текст. Результат получается так себе, код Костя пишет намного быстрее и лучше.

Написать короткую статью на страницу или пофиксить двенадцать новых багов? Несложный выбор.

История 4: бесконечно выносливая Марина

Марина отвечает за техническую поддержку и отлично знает продукт. Она помогает пользователям разобраться с настройками и передаёт разработчикам найденные баги. В техподдержку пишут часто, но Марина очень продуктивная — успевает обработать все запросы за полдня.

Со временем система обрастает новыми фичами, добавляются новые сервисы, перепиливаются старые. Количество запросов увеличивается в геометрической прогрессии. Теперь Марина занята весь день, и у неё не хватает времени попить кофе.

Марина рассчитала: если дело так пойдёт и дальше, скоро придётся работать не по 8 часов в день, а по 19. Она просит нанять ей кого-нибудь в помощь. Требования к новичку скромные: ему предстоит просто копировать готовые ответы Марины, ведь многие вопросы пользователей повторяются.

История 5: проактивный Вадим и его эмпирические правила

Вадим — верховный менеджер. Он распределяет задачи между членами команды и следит за их выполнением. Не то чтобы Вадим против документации, просто он использует матрицу Эйзенхауэра, для него важно деплоить новые фичи. Документация для Вадима не в приоритете, её всё равно никто не читает. Да и непрофильная это активность для программистов — статейки писать.

Когда-то давно Вадим уже нанимал специалиста, который написал для команды пользовательскую документацию по ГОСТ, эта документация даже сохранилась. Вадим вспоминает закон Парето и убеждает себя, что какая-то документация значительно лучше, чем никакой. Даже если она в последний раз обновлялась при Медведеве, и в ней написано: «API-доки нет, но вы держитесь в любой непонятной ситуации пишите Марине».

История 6: код, текст и роботы

Доку писать никто не хотел, а технологическая сингулярность уже наступила. Поэтому к работе подключился Кинолай Оринов — человек и нейросеть. Кинолай генерил тексты намного быстрее Кости. «То, что надо!» — подумали все.

Правда чтобы Кинолай написал документацию для инновационной системы, надо Кинолаю сначала эту систему со всех сторон показать. Иными словами, придётся пустить чужой AI в свою проприетарную кодовую базу.

Такое решение сочли небезопасным: мало ли что у Кинолая на уме.

История 7: а как могло бы быть?

Кажется, у команды скопились задачи, с которыми справится только один человек:

Что изменилось бы, если бы Даня включился в работу сразу?

  1. Знания об архитектуре сохранились бы в документации и в Амстердам с Олегом не уехали. В любой команде есть текучка кадров, поэтому безопаснее, если важные знания сосредоточены не только в головах, но и в документах.

    Диме, принявшему пост главного архитектора, такие документы очень бы пригодились. Документация надёжнее, чем код: Дима смог бы быстрее изучить устройство системы и разобраться в идеях Олега. Даже из самых подробных комментариев в коде Дима не понял бы, почему выбран именно такой технологический стек. А ещё при переносе идей из головы в код почти всегда возникают баги, а при переносе в документацию — как правило, нет.

    Возможно, благодаря этим знаниям Дима отказался бы от рефакторинга.

  2. Даня спроектировал бы внутреннюю базу знаний, разобравшись в потребностях команды. В базе знаний хранились бы и коротенечко описанные новые фичи, и онбординговые документы. Диме не пришлось бы становиться стендапером на полставки, а программисты вроде Кости со спокойной душой бы фиксили баги.

    Внутренние документы здорово экономят время команды. База знаний, как единый источник информации — отличная альтернатива бесконечным вопросам в Slack про одно и то же. Сэкономленное время — это деньги, чему был бы очень рад менеджмент в лице Вадима.

  3. Даня актуализировал и поддерживал бы пользовательскую документацию. Техподдержка в лице Марины сказала бы ему спасибо: дурацких вопросов стало бы меньше, и её рабочий день заканчивался бы вовремя.

    Хорошая пользовательская документация значительно сокращает трудозатраты и снимает лишнюю нагрузку с техподдержки. Это порадовало бы и Вадима, потому что клонировать Марину оказалось дороговато.

А с Кинолаем Даня бы подружился, ведь с его помощью удалось бы автоматизировать часть работы. Правда заставить роботов писать документацию пока не получится.

Нейросети действительно уже научились писать связные тексты, но документация — это не просто текст. Чтобы написать этот текст, нужно знать не только саму предметную область, нужно также понимать контекст, аудиторию, её нужды и уровень. Возможно, однажды Кинолай научится и этому. Но к тому времени он заодно и код научится писать, и тогда всей команде можно будет ехать к Олегу в Амстердам.

Но это уже другая история.


Если вашему проекту жизненно необходима документация, приходите к нам в documentat.io. Мы разрабатываем техническую документацию на заказ и предоставляем техписателей на аутстаффинг. А ещё мы учим писать документацию — возможно, с помощью наших курсов вы сможете вырастить своего собственного Даню.

Автор текста: Ната Мелихова

Теги:
Хабы:
Всего голосов 16: ↑15 и ↓1+17
Комментарии12

Публикации

Информация

Сайт
documentat.io
Дата регистрации
Дата основания
Численность
11–30 человек
Местоположение
Россия