Карты, золото и специи: почему пренебрежение документацией может погубить ваш проект

Что было самым ценным, что исследователи прошлого привозили домой из своих путешествий? Золото и специи? Неправильно. Карты.

Христофор Колумб никогда бы не совершил свое знаменитое путешествие в 1492 году без карта разработанная его предшественниками. Шпионская игра с целью получения португальских карт заложила основу Голландской Ост-Индской компании, возможно, самой дорогой компании в истории человечества. На пике своего развития в 1637 году она стоила 78 миллионов голландских гульденов, что эквивалентно 7,9 триллиона долларов в долларах 2017 года. Это более 10 триллионов долларов в деньгах 2024 года, больше, чем у Microsoft , Nvidia и Apple комбинированный Ощутимые сокровища из новых земель были важны в краткосрочной перспективе, но в долгосрочной перспективе именно знания ковали настоящие состояния.

Почему в современном мире технологий мы склонны забывать об этом? В погоне за немедленным успехом мы часто неохотно тратим драгоценное время и ресурсы на создание и поддержание технической документации. Говоря терминами 17-го века, мы спешим схватить золото и специи, не нанося на карту, которая, в свою очередь, могла бы привести нас к гораздо большему количеству золота и специй. Вы скептически настроены? Эй, давайте взглянем поближе…

Странный код

«Как вы, несомненно, помните, гипноидный застой нейронных структур мозга можно сканировать с помощью сверхэлектромагнитного луча, который —» «Да ладно!» — нетерпеливо сказал Ард Варк. «Что вы имеете в виду — как мы, несомненно, помним?» Как мы можем помнить это, если мы никогда этого не знали? — Эта цитата из «Wacky World», рассказа великого писателя-фантаста Эдмонда Гамильтона, относится к марсианам, а не к программистам. Однако многие люди считают разработчиков пришельцами с другой планеты — особенно те, кто имеет лишь смутное представление о разработке программного обеспечения и ее сложностях. Дело в том, что разработчики часто предполагают, что другие знают код так же хорошо, как и они, и часто считают техническую документацию ненужной. Такой образ мышления рискует сделать проект таким же сложным и непонятным для посторонних, как «гипноидный застой», что в конечном итоге ставит под угрозу потенциальный успех проекта.

Нежелание создавать документацию часто возникает по тем же причинам, по которым люди откладывают дела на потом в других областях: это требует значительных временных и финансовых вложений. Другими словами, это часто происходит из-за банальной лени и желания сэкономить деньги, которые не так-то просто преодолеть. Однако документация — это не просто избыточная информация, которая, как предполагается, очевидна для всех; она содержит критически важные детали, которые могут быть незаменимы. Часто отсутствие документации значительно усложняет обнаружение и исправление ошибок, затрудняет обслуживание и обновления и увеличивает время, необходимое для приема новых членов команды. В то время как команды без документации застревают, выполняя повторяющиеся задачи, проекты с хорошо структурированной документацией показывают высокую эффективность и надежность — это факт, а не просто мнение.

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

Фактор автобуса, Burnout и другие фантастические твари

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

История №1: Неспособность масштабироваться

Проект «NoDocumentationPlease», изначально успешный стартап по потоковой передаче видео, столкнулся с серьезными проблемами при попытке масштабирования из-за плохой технической документации. Когда команде потребовалось расширение, новые сотрудники не могли полностью понять свои задачи, и никто не мог дать им адекватного объяснения. Без должной поддержки и обучения новые сотрудники быстро уходили. Это не только замедлило ход проекта, но и привело к потере ключевых талантов, в конечном итоге поставив под угрозу общую эффективность и будущее проекта. В результате стримеры покинули чат, и проект был закрыт.

История №2: Проблемы с обслуживанием

Компания «IKnowEverything» разработала облачную платформу для синхронизации и хранения данных. Изначально проект развивался быстро, но со временем ее разработчики столкнулись с трудностями в поддержке и обновлении платформы из-за отсутствия четкой и актуальной технической документации. Это привело к замедлению разработки, появлению большего количества ошибок и недовольству клиентов. В конечном итоге компания начала терять старых клиентов, а новые клиенты выбирали конкурентов с более стабильными и надежными решениями. Доходы значительно снизились, а стоимость неэффективного обслуживания выросла. Правильное документирование технических аспектов с самого начала могло бы позволить им успешно масштабироваться. Однако это не было сделано вовремя. В результате компания не смогла преодолеть технические и финансовые трудности и была закрыта.

История №3: Выгорание разработчика

Проект "SmartestEver" столкнулся с серьезными проблемами, поскольку его главный разработчик Эндрю, который занимался практически всем, ушел в отставку после того, как его перегрузили многочисленными вопросами команды. Если бы у "SmartestEver" была надлежащая документация, младшие разработчики могли бы легко обратиться к FAQ и решить рутинные проблемы. Вместо этого они забросали Эндрю вопросами, а без него и необходимой документации команда просто не смогла продолжить работу, и проект был закрыт (нажмите F для Эндрю).

История №4: Фактор автобуса

В компании «NoDocsNeeded» перспективный программный продукт разрабатывался Джоном, ключевым разработчиком, который обладал всеми знаниями, но не удосужился их задокументировать. Его менеджеры также не потрудились его уговорить. Настал день, когда Джон уехал в командировку и просто не вернулся. Без документации или понимания архитектуры и логики продукта оставшиеся члены команды по сути ничего не могли сделать. Проект был заморожен, а вложенные в него деньги были потрачены впустую. Урок прост: документация и распределение знаний внутри команды имеют решающее значение для того, чтобы избежать зависимости от одного человека. Кстати, они все еще ищут Джона…

История №5: Ни один пророк не приветствуется в Open Source

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

От юнги до капитана

Хорошо, у нас есть немного теории и практики, теперь давайте погрузимся в исследования и статистику. Опрос разработчиков Stack Overflow 2024 состояния что 84% респондентов используют техническую документацию для понимания функциональности технологий. Однако даже с документацией они часто не могут найти нужные им ответы, как показывают следующие по популярности ресурсы: Stack Overflow (80%), письменные руководства (68%), блоги (61%) и видеоинструкции (54%). Microsoft Research: повседневная жизнь разработчиков программного обеспечения найденный что в среднем разработчики тратят 1-2% своего дня (8-10 минут) на документацию, а 10,3% разработчиков говорят, что устаревшая документация заставляет их тратить слишком много времени на поиск ответов самостоятельно. Необходимость документации также является серьезной проблемой для академического сообщества. Простой поиск в Google Scholar по запросу <"documentation" AND "software"> урожайность более 4 миллионов результатов, что явно указывает на огромное количество научных публикаций, посвященных этой проблеме.

Основные выводы поразительно просты: #1 – Всем нужна документация, когда дело касается понимания технологий и/или работы других людей; но #2 – Мало кто утруждает себя ее написанием и поддержкой; и, следовательно, #3 – Большая часть документации плохо написана, устарела и в целом бесполезна. Так что же нужно сделать? Измените свою мотивацию на всех уровнях.

Группа исследователей из Университета прикладных наук HAN и Университета Гронингена (оба в Нидерландах) идентифицированный наиболее типичные проблемы с технической документацией:

• Неофициальная документация, часто используемая разработчиками, сложна для понимания;

• Документация считается отходами, если она не вносит непосредственный вклад в конечный продукт;

• Производительность разработчика измеряется только объемом работающего программного обеспечения;

• Документация часто не соответствует реальному программному обеспечению;

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

  
  

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