✍️ Почему отсутствие технической документации убьёт ваш проект?

Объясняю, почему техническая документация важна, а её наличие – обязательная составляющая успеха проекта. Не верите? 5 (почти) реальных историй, представленных в этой статье, вас убедят!

«...Как вы, конечно, помните, гипповидный стазис нейронной сети головного мозга можно прочесть экстра-электромагнитным лучом, который… — Хватит! — нетерпеливо перебил Ард Барк. — Что это значит: «как вы, конечно, помните»? Как мы это можем помнить, когда мы этого совсем не знаем?».

Вышеприведённая цитата величайшего фантаста Эдмонда Гамильтона касается марсиан, а не программистов, но и на последних нередко глядят как на представителей иной цивилизации – особенно те, кто о разработке и её сложностях имеет представление весьма слабое. Факт: примеряя на других собственные мерки, разработчики забывают, что не все знают код так же хорошо, как они, и зачастую считают составление технической документации излишним. А потому рискуют сделать проект таким же сложным и непонятным для непосвящённых, как и гипповидный стазис – и в итоге загубить его на корню, даже если, в общем и целом, у него были прекрасные перспективы. Рассказываю, почему техническая документация – это важно, а её наличие – обязательная составляющая успеха проекта.

Документация: за и против

Причина, по которой возникает нежелание делать документацию, мало отличается от тех, что заставляют откладывать дела в других ситуациях: её составление (а впоследствии – ещё и поддержка) требует значительных временных и финансовых затрат. Иными словами, всему виной – банальные лень и жадность(экономия), побороть которые не так легко.

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

Да, встречаются программисты, которые утверждают, что они пишут такой «понятный и чистый» код, что документация им не нужна. Однако на деле они мало отличаются от марсиан, втирающих про гипповидный стазис, ведь даже самый идеальный код может быть непонятен другим разработчикам или потерять свою ясность со временем. То, что кажется понятным сегодня, может стать большой загадкой чуть позже. Вы, например, справитесь с простейшей перфолентой из 70-х?

А что говорят исследования?

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

1. Stack Overflow Developer Survey 2023 утверждает, что 90.36% респондентов используют техническую документацию для ознакомления с функционалом технологий. При этом те же данные показывают, что даже так им не всегда удаётся найти ответы на нужные вопросы, поскольку следом идут Stack Overflow (82.56%) и блоги (76.69%).

2. Исследование Microsoft Research: The Daily Life of Software Developers показало, что в среднем разработчики тратят на документацию 1-2% своего дня (8-10 минут), а 10,3% разработчиков уверяют, что из-за устаревшей документации им приходится тратить слишком много времени на самостоятельный поиск ответов на свои вопросы.

Необходимость документирования серьёзно беспокоит и научное сообщество: в этом легко убедиться даже благодаря простому поисковому запросу в Google Scholar <"documentation" AND "software">. Более 3,700,000 результатов – явное свидетельство наличия огромного количества научных публикаций, так или иначе затрагивающих поднятый вопрос. Во множестве работ рассматривается не меньшее количество проблем, которые влияют на качество разрабатываемых программных продуктов. Доказано, что неэффективное или неполное документирование может привести к увеличению времени на отладку и тестирование, повышению стоимости проекта и ухудшению его управляемости. Также подчеркивается важность документации для обеспечения согласованности и совместимости внутри больших команд, работающих над сложными проектами.

Окей, скажете вы, документация – вещь неплохая, но разве её отсутствие так уж и убьёт проект? Показываю, как это возможно на примерах – вымышленных, но, как говорится, based on true stories.

История №1: невозможность эффективного масштабирования проекта из-за отсутствия документации

Проект «НеЛюблюДокументацию», изначально успешный стартап в области стриминга видео, столкнулся с серьёзными проблемами при попытке масштабирования из-за отсутствия адекватной технической документации. А всё потому, что, когда возникла необходимость в расширении команды, новые сотрудники не могли толком понять, что им делать, а объяснить толком никто не мог. Осваивать сложный код и проектные задачи без должной поддержки и обучения никому не хотелось, и новички быстро увольнялись. Что не только замедлило прогресс проекта, но и привело к потере ключевых талантов, а в итоге и вовсе подорвало общую эффективность проекта и даже поставило под угрозу его дальнейшее существование. Итог: стримеры вышли из чата, проект закрылся.

История №2: из-за отсутствия документации возникли сложности в обслуживании и обновлении проекта

Компания «ЯиТакВсеЗнаю» разработала облачную платформу для синхронизации и хранения данных. Первоначально проект развивался быстро, но с течением времени разработчики столкнулись с затруднениями в обслуживании и обновлении платформы – и всё из-за отсутствия чёткой и актуализированной технической документации. В итоге это привело к замедлению разработки, появлению ошибок и недостатков в новых версиях продукта, и клиентам это совсем не нравилось.

В конце концов, компания начала терять своих старых пользователей, а новые клиенты выбирали «ЯиТакВсеЗнаю» всё реже, предпочитая конкурентов, у которых были более стабильные и надёжные решения. У компании в разы сократились доходы, хотя расходы на неэффективное обслуживание только росли. Чем всё закончилось? Правильно: будучи не в состоянии преодолеть многочисленные технические и финансовые трудности, «ЯиТакВсеЗнаю» закрылась и канула в лету. А ведь могла бы просто вовремя составить техническую документацию и масштабироваться в регионы.

История №3: отсутствие документации – причина выгорания программистов

Проект «СамыйУмный» столкнулся с серьёзными проблемами из-за недостатка технической документации – а всё потому, что основной разработчик Андрей, на котором держалось абсолютно всё, уволился, устав от многочисленных вопросов команды. Будь у «СамогоУмного» всё как положено, младшие программисты преспокойно бы обращались к FAQ и легко решали служебные вопросы. Вместо этого они доконали Андрея, а эффективно продолжить работу в отсутствие компетентного специалиста и необходимой документации так и не сумели. Итог прежний: проект закрылся (Андрей, press F).

История №4: проблемы передачи знаний / bus-фактор

В компании «ДокументацияНеНужна» разрабатывался перспективный программный продукт, работой над которым занимался один ключевой разработчик – Иван. Он обладал всеми знаниями о проекте, но не занимался составлением технической документации. Когда Иван уехал в командировку, из которой совершенно неожиданно не вернулся, проект оказался в критическом положении: без документации, понимания архитектуры и логики работы программы оставшиеся члены команды не смогли продолжить разработку. Проект был заморожен, а деньги потрачены (причём впустую). Мораль: важно не только документирование, но и распределение знаний внутри команды, чтобы проект не зависел от одного человека. Итог: проект закрылся, Ивана всё ещё ищут.

История №5: люблю opensource, но не люблю документацию

Марина сделала свою первую опенсорс-библиотеку, но не написала к ней документацию. Никто так и не узнал, что же эта библиотека делает, а Марина решила, что больше она не будет писать никаких библиотек, потому что это всё равно никому не нужно.

Итог: проект закончился, даже не начавшись, а Марина ушла из профессии.

Так что же получается?

Проект действительно может существовать без документации, но только в краткосрочной перспективе. Её отсутствие может привести к ситуациям, когда знания сосредоточены у ограниченного числа людей, а это многократно увеличивает риски для проекта при их уходе или недоступности. Кроме того, длительное игнорирование разработки документации неизбежно приведет к проблемам в управлении, обслуживании и развитии проекта. Именно поэтому составление технической документации — это не просто рекомендация, а обязательный элемент успешного и устойчивого проекта, важность которого подтверждена многолетним опытом и научными исследованиями. Не будьте как Иван, Андрей или Марина: позаботьтесь о составлении качественной технической документации, и желательно заранее!