Время идет, планета крутится, системы растут и развиваются, а я продолжаю слышать в кругах аналитиков сожаление: «Эх, пришел на проект, а тут никакой документации, смотрим в код».
Но это ерунда. Хуже, когда заказчик говорит: «Создали два разработчика. Уволить не могу, хотя почти ничего не делают, только по мелочи донастраивают. А с этой системой у нас уже и бухгалтерия интегрирована, и … Документация? Нет ее. А надо.
Спасите-помогите»!
Проблемы с документацией в процессе разработки ПО были, есть и будут. Эта статья посвящена поиску момента, в который появляется необходимость ведения проектной документации и поможет принять решение, если у вас только начали появляться мысли об этом. Повествование сопровождается примерами из жизни МоегоСклада.
Что это за зверь — «документация»?
С чего начинается задача на разработку? С идеи. Чтобы что-то создать, нужно это представить в своей голове. Чтобы не потерять мысль, её лучше зафиксировать.
Что такое проектная документация?
По сути, документирование — это процесс описания идеи от момента ее возникновения в сознании до выпуска результатов в релиз. А значит документировать мы начинаем в момент написания ТЗ, при описании задачи, без строгого формата, в картинках или на листе бумаги. Когда мы формализуем, как это должно работать.
Для кого документировать?
Если нет понимания, кому нужна проектная документация, то она не нужна. Возможно, прочитав эту статью чуть дальше, мнение может резко поменяться, но это не точно.
В первую очередь документация нужна команде разработки и заказчику.
Разработчик быстрее осознает, над чем он вообще трудится, спокойнее принимает «чужое наследство».
Тестировщик каждый раз не находит одни и те же ошибки, которые на самом деле уже стали особенностями реализации.
Для бизнес-заказчика наличие минимальной документации, описывающей изнутри его программный продукт, позволяет не быть в рабской зависимости у своих разработчиков или подрядчиков.
Иногда проектная документация нужна просто потому, что так сказали.
На мой взгляд, это самый омерзительный случай — страдают все: и те, кто пишет документацию – нудно, скучно, бессмысленно потраченные силы на соблюдение каких-нибудь ГОСТов, и те, кто потребляет ее – обязанность заказать и оплатить документацию по ГОСТу, потому что так надо.
Конечно, результаты такой деятельности частично оправданы, много полезных знаний сохраняется по итогам разработки, но порой вместе с таким же количеством бесполезных.
Служба эксплуатации, техническая поддержка и, конечно же, пользователи любят документацию. Чем больше написано в открытом источнике о способе решения задач или проблем, тем меньше они друг с другом взаимодействуют. Экономия ресурсов со всех сторон вполне очевидна.
Что такое рабочая документация в строительстве и зачем она нужна
Причины, по которым компании приходят к внедрению документирования
Масштаб проекта – основная и единственная причина, по которой появляется необходимость внедрения документирования. Процесс масштабирования стоит рассматривать во всех возможных смыслах, касающихся разработки.
Есть сервис МойСклад и 2007 год. Прекрасный пример стартапа от двух разработчиков. Фундамент сервиса был целиком заложен Аскаром (генеральный директор) и Олегом (технический директор). Если почитать историю создания МоегоСклада, то можно узнать интересный факт – уже тогда было неосознанное документирование продукта в рабочей тетрадке в клеточку!
Любые знания, зафиксированные на материальном или цифровом носителе, представляют из себя ту самую проектную документацию, которая впоследствии помогает устанавливать причины: почему эта кнопка работает именно так, а не иначе.
На момент, когда у продукта было 0 пользователей, лэндинг и рабочая альфа-версия, документировать было бессмысленно. Да и сейчас любой самостоятельной команде разработчиков, запускающих стартап, уверена, документировать не надо – вы сами творите свое «сокровище» и знаете его. Лучше докрутить еще парочку фич, чем заниматься печатью лишних символов с описанием системы для себя. Время бесценно. А вот тем, кто заказывает разработку стартапа, я советую задуматься, в какой момент они могут пожелать заменить подрядчика и начинать строить свою команду.
Пример с автомастерской
Есть среднестатистическая мастерская с механиком, которому регулярно привозят примерно одинаковые машины.
В зависимости от опыта он успешно будет чинить обычные автомобили: не глядя в инструкции, не советуясь со старшим мастером. Интуиция спасет его.
Так и с программными системами. Для опытного разработчика они все примерно одинаковые, только работают немного по-разному и названия отличаются.
Привезут в автомастерскую сломанную «буханку». Опытный механик постучит молотком по нужным частям, и она поедет. А постучит, возможно, даже наугад! Это сопоставимо с тем, что опытный разработчик придет в разработку простой системы и будет решать задачи как получится, наугад. И все будет получаться, потому что никаких сложных связей и соединений внутри нет — например, какой-нибудь интернет-магазин с информационным сайтом или что угодно другое.
Привезут в автомастерскую опытному механику какой-нибудь Hyundai Solaris. Даже если он последнего года выпуска, даже если механик его впервые видит и до этого работал на Volkswagen, он не растеряется и, применив интуицию, починит его.
Опять же это сопоставимо с ситуацией, когда опытный разработчик, который, посмотрев на существующий программный код, сможет оценить, куда ему пристроить новую фичу и сделать всё по шаблону или «как сердце подскажет».
И все успешно получится, потому что система обычная, никаких «наворотов» нет.
Но вот привезли Aston Martin или Ferrari. А я обычный механик в среднестатистической автомастерской. Конечно, сначала я обрадуюсь такому. Но потом, когда дело дойдет до ремонта, я буду вдумчиво смотреть на это «чудо света» и искать все возможные инструкции, чтобы устранить неисправность.
Так и с программной системой! Приходящие разработчики видят «нечто» и пытаются понять, как с этим жить. Большая часть рабочего времени уходит на погружение в контекст: вдумчивый осмотр и изучение, а не на саму разработку.
Если система простая, то документировать необязательно. Но если внутри нее, «под капотом», какой бы простой она не казалась для пользователей, появляются архитектурно сложные решения, то документирование становится важной необходимостью.
В отсутствии проектной документации основная стоимость разработки будет потрачена на изучение того, «как оно работает», «что это» и «почему так».
За 13 лет МойСклад смог очень круто подрасти: веб-приложение для RU- и US-площадок, кассовое ПО для трех платформ, мобильные приложения, шесть протоколов API и много-много всего.
Продукт простой снаружи, для пользователя, но сложный внутри — для разработки и развития. Я, как ведущий системный аналитик, шла в компанию с желанием описать все быстро и продолжать развивать документированный продукт.
Когда я открыла «капот» дорогого и любимого Aston Martin, я поняла, что взяла очень интересную и сложную машину. Сначала было длительное изучение «начинки», а теперь нужно время, чтобы успевать и развивать новое, и описывать ранее созданные детали.
Одна из основных причин начала накопления знаний в МоемСкладе – продукт стал большим и сложным.
Настал момент, когда пора документировать. Этот процесс начался еще три года назад тестировщиками, которые описывали все особенности реализации и ключевые моменты поведения системы после выпуска очередной задачи в релиз.
Причиной запуска такой деятельности стало то, что ведущий QA тратила много времени на обучение продукту новых сотрудников и рассказы про одно и то же. Да и некоторые знания забываются и теряются, потому что есть золотое правило «не трогай то, что работает».
Собранные командой тестирования документы и сегодня помогают ориентироваться в том, как работают части МоегоСклада: что считать нормой, а что нет.
Программный код и есть документация
Так говорят разработчики. И нет, это не так.
Во-первых, не все любят вникать в чужой код, а особенно, если это «наследство» досталось не от самого пряморукого разработчика. Поэтому, если ваша команда настаивает на том, что документировать не надо, то могут всплыть «подводные камни».
Во-вторых, не все умеют читать программный код, и он не раскрывает ожидаемый результат. Команда тестирования, которая принимает задачи на проверку, должна понимать, какой реакции ждать от системы. В обязанности тестировщика не входит чтение программного кода. Поэтому когда он погружается в контекст задачи, по требованиям может быть понятно, как должна работать новая функциональность, но совершенно непонятно, чего ждать от ранее реализованной. Проектная документация может устранить лишние вопросы.
Иногда код со встроенной документацией может спасать продукт, но все же это не полноценное решение проблемы. Не-разработчикам тяжело работать с таким видом описания: структура и формат неподходящие. Но немного проблему документирования это решает.
Как нас много
Как масштаб проекта по части количества людей влияет на необходимость появления документации.
Сервис МойСклад начинался с Аскара и Олега 13 лет назад. Целиком знают продукт всего три человека: Аскар, Олег и Максим — присоединившийся к ним немногим позже продакт и бизнес-аналитик.
Сегодня компания насчитывает более 150 человек. Три хранителя знаний на тридцать сотрудников? Возможно. А на команду от ста человек? Да и помнить все детали, особенно когда реализовывал их не ты, просто невозможно.
Поэтому нормой стал ответ «смотри как на проде».
Если каждый новый сотрудник будет начинать уточнять как работает та или иная часть системы при получении новой задачи, то он будет отнимать время у коллег. Изменению подвергаются самые разные части Склада. Не всегда удается установить их истинное поведение, которое задумывалось изначально.
Может ответить только зафиксированное знание, которое либо есть, либо нет, либо оно в человеке (а значит его нет).
В МоемСкладе стали важными такие умения, как «археология по коду» у разработчиков, «археология по возможностям системы» у тестировщиков и аналитика.
Эти навыки стали ключевыми и их стоило вносить в описание вакансий. Ими обладают далеко не все на рынке труда, да и никто особо этим заниматься не хочет.
Не храните знания в людях – это опасно
Рынок IT-специалистов очень бодр и динамичен. Отсутствие документации на продукт может быть опасным. Человек, уходя из компании, уносит с собой знания о тех частях, которые он делал. Это плохо тем, что развитие и сопровождение неизведанных частей становится очень дорогим удовольствием – нужно исследовать, как работает сейчас и достраивать над текущим поведением нечто новое.
У бизнес-заказчика при смене подрядчика возникнет очень много вопросов с передачей кода новой компании: «наследство» не любят, особенно, недокументированное. Бизнес-заказчику без документации может быть сложно стать независимым.
Сегодня все более актуальна тема с удаленной работой, да и ранее команды разработки всегда обсуждали задачи в чатах (Slack, Telegram, Skype и т.д.).
В какой-то момент жизни продукта может настать перевес: переписки у разработчиков занимают больше рабочего времени, чем решение задач.
Слишком дорого начинают обходиться разговоры. Нужно своевременно отлавливать этот момент и начинать документировать, чтобы погружение в контекст новых сотрудников проходило легче, без лишних переписок и созвонов.
Моя позиция такова: стараюсь минимизировать развернутые ответы на вопросы в чатах и максимально ссылаться на существующую документацию:
Разработчик: [Вопрос]
Я: [ссылка на Confluence] п. [название]
Это куда быстрее, чем каждый раз отвечать всем на одни и те же вопросы. Если вопрос возник, значит ответ на него надо документировать. Такая вот простая логика.
И про контекст
Итого: где же тот самый момент?
Взгляните на продукт и оцените его масштаб со всех возможных сторон. Если он становится большой и сложный, то кажется, пора начинать внедрять процесс его описания.
Некоторые компании начинают с первых дней, а некоторые тянут до последнего. Но начинать никогда не поздно. Через 5 лет, через 10 или 13 — главное не пытаться прятать голову в песок, когда становится заметно, что сотрудникам сложно работать и есть проблемы с пониманием системы.
Что может дать наличие документации на программный продукт?
- Меньше обсуждений в чатах и поисков причин «почему так».
- Быстрее погружение в контекст.
- Команде проще понимать и оценивать объем изменений для новых задач.
Ссылки
analystdays.ru/ru/talk/83497 Analyst Days. Как мы процесс документирования внедряли
habr.com/ru/company/moysklad/blog/452016 Сервис МойСклад 12 лет в облаке (уже 13!)
Источник: habr.com
Разрабатывать один и тот же проект дважды не выгодно никому. Но законодательство обязывает
С прошлого года в Градостроительном кодексе кроме понятия «проектная документация» появилось еще одно — «рабочая документация». Вроде бы это снимает часть проблем, с которыми сталкивались застройщики в зоне реализации своих проектов. Тогда почему же эксперты называют данное решение половинчатым и призывают вернуться к одностадийному проектированию?
Фото: pixabay —>
С прошлого года в Градостроительном кодексе Российской Федерации (ГрК РФ) к понятию «проектная документация» прибавилось еще одно — «рабочая документация». Все бы хорошо, говорят профессионалы, если бы закон № 275-ФЗ от 1 июля 2021 года, который ввел это понятие в кодекс, не привел бы лишь к минимизации срока и объема финансирования строительства.
«На наш взгляд, в сложившейся экономической ситуации эти изменения в качестве поддержки строительной отрасли и упрощения строительного процесса выглядят как полумера», — отметил в беседе с Business FM ведущий эксперт отдела выездных проверок и взаимодействия с надзорными органами межотраслевой ассоциации СРО в области строительства и проектирования «Синергия» Юрий Синюков.
Как осуществлялось проектирование и прохождение экспертизы до прошлого июля? Подготовив проектную документацию, застройщик или технический заказчик направлял ее на государственную или негосударственную экспертизу. После прохождения экспертизы и начала строительства контроль осуществлялся по проектной документации, но она в ходе работы подвергалась корректировке и очень часто отличалась от рабочей документации, по которой в реальности шла стройка.
«Например, когда составляли рабочую документацию, уточняли, какой завод может поставить оборудование; еще что-то менялось — заказчик иногда вносил поправки, которые улучшали проект, предлагал какие-то технические решения, новые, недавно появившиеся на рынке материалы, и в итоге рабочая документация отличалась от проектной. При этом надзорные органы в соответствии с ГрК РФ и нормативными документами осуществляли контроль именно по проектной документации, которая прошла экспертизу и утверждена заказчиком. В результате в связи с тем, что появлялись разночтения, необходимо было вносить изменения в проектную документацию. А стало быть, экспертизу проекта приходилось проходить повторно», — поясняет Юрий Синюков.
Конечно, на строителей могли накладываться (и накладывались) штрафы за то, что они строят с отступлением от утвержденных документов. Ведь по правилам, если надзорные органы выявили несоответствия, организация должна приостановить работы до устранения нарушений — в данном случае до тех пор, пока рабочая документация не будет приведена в соответствие с проектной: необходимо внести изменения в проектную документацию, затем еще раз пройти экспертизу, и только после этого можно продолжать работать. А если таких несоответствий в период строительства выявляется несколько, то по-хорошему надо проходить несколько экспертиз. По наблюдениям Юрия Синюкова, строители или заказчики часто поступали по-другому: собирали все несоответствия, продолжали строить и после завершения строительства все эти «неполадки» устраняли за один раз, проходя повторную экспертизу проектной документации перед сдачей объекта в эксплуатацию.
Сейчас все стало проще. Согласно внесенным в ГрК РФ изменениям, после разработки проектной документации и прохождения всех этапов ее согласования и утверждения в соответствующих ведомствах осуществляется подготовка рабочей документации. Надзорные органы при рассмотрении соответствия построенного объекта проектной документации должны еще проверять (если она им представлена) и рабочую документацию. Если в ней есть какие-либо изменения, улучшающие или немного изменяющие первоначальный вариант, то больше не требуется вносить изменения в проектную документацию и заново проходить экспертизу. И это хорошо.
Однако Юрий Синюков все-таки называет решение половинчатым: хотя при необходимости закон позволяет вести подготовку проектной и рабочей документации и их согласование одновременно, куда чаще между двумя стадиями проектирования образуется большой временной разрыв. К тому же нередко подготовку проектной и рабочей документаций осуществляют разные проектные организации, и при возникновении разночтений появляется конфликт интересов между ними, подчеркивает эксперт.
Юрий Синюков ведущий эксперт отдела выездных проверок и взаимодействия с надзорными органами межотраслевой ассоциации СРО в области строительства и проектирования «Синергия» «Невольно возникает вопрос: зачем дважды разрабатывать один и тот же проект строительства — сначала концептуально и проходить по нему экспертизу, а затем детально, чтобы строить? Ведь на деле инвестору или, например, государству невыгодно дважды тратить средства на проектирование и затягивать строительство. Оптимальным решением было бы, на наш взгляд, одностадийное проектирование — назовем это, например, «рабочий проект». Благодаря такому решению значительно сократились бы сроки строительства, удалось бы оптимизировать все строительные процессы — от момента подготовки проектной документации и прохождения экспертизы до строительства объекта и дальнейшей корректировки проекта».
По словам эксперта, плюсы одностадийного проектирования очевидны. Это прежде всего минимизация затрат: экспертиза проводится лишь по «рабочему проекту», а далее заказчик его утверждает и ставит штамп «В производство работ». Кроме того, происходит сокращение сроков проектирования, и, как следствие, появляется возможность попадания в прайсы поставщиков материалов и оборудования при строительстве. В свою очередь инвесторам это позволяет в сжатые сроки вводить объекты в эксплуатацию и, как следствие, быстрее получать доход от вложений. Стало быть, значительно повышается рентабельность объектов.
«Наконец, принимая во внимание требования постановления правительства № 331 от 05.03.2021 для госзаказчиков — об обязательной разработке информационной модели объекта капитального строительства с 2022 года, тем более необходимо пересмотреть вопрос о действующей системе проектирования в отечественной отрасли. На сегодняшний день наиболее приемлемым вариантом было бы детализировать «рабочий проект» для возможности строительства с учетом современных требований», — уверен Юрий Синюков.
При этом в будущем, по его мнению, стоит отказаться уже и от «рабочего проекта» в пользу цифровой модели объекта капитального строительства. «В 2019 году в ГрК РФ появилось понятие «информационная модель». Эта модель может быть дополнением к рабочей документации или вообще ее заменой. На наш взгляд, со временем, скорее всего, отпадет необходимость в разработке проектной документации и проведении экспертизы: если мы разрабатываем информационную модель в электронном виде, то после мы ее же отправляем на экспертизу и потом по ней же начинаем строить. В процессе строительства информмодель просто дополняется информацией о характеристиках и стоимости примененных материалов, о каких-либо изменениях, произошедших в период строительства, и затем финальный ее вариант уже идет дальше, в эксплуатацию», — делится своим видением будущего Юрий Синюков.
Источник: www.bfm.ru