Время идет, планета крутится, системы растут и развиваются, а я продолжаю слышать в кругах аналитиков сожаление: «Эх, пришел на проект, а тут никакой документации, смотрим в код».
Но это ерунда. Хуже, когда заказчик говорит: «Создали два разработчика. Уволить не могу, хотя почти ничего не делают, только по мелочи донастраивают. А с этой системой у нас уже и бухгалтерия интегрирована, и … Документация? Нет ее. А надо?.. Спасите-помогите»!
Проблемы с документацией в процессе разработки ПО были, есть и будут. Эта статья посвящена поиску момента, в который появляется необходимость ведения проектной документации и поможет принять решение, если у вас только начали появляться мысли об этом. Повествование сопровождается примерами из жизни МоегоСклада.
По сути, документирование — это процесс описания идеи от момента ее возникновения в сознании до выпуска результатов в релиз. А значит документировать мы начинаем в момент написания ТЗ, при описании задачи, без строгого формата, в картинках или на листе бумаги. Когда мы формализуем, как это должно работать.
Если нет понимания, кому нужна проектная документация, то она не нужна. Возможно, прочитав эту статью чуть дальше, мнение может резко поменяться, но это не точно.
В первую очередь документация нужна команде разработки и заказчику.
Разработчик быстрее осознает, над чем он вообще трудится, спокойнее принимает «чужое наследство».
Тестировщик каждый раз не находит одни и те же ошибки, которые на самом деле уже стали особенностями реализации.
Для бизнес-заказчика наличие минимальной документации, описывающей изнутри его программный продукт, позволяет не быть в рабской зависимости у своих разработчиков или подрядчиков.
Иногда проектная документация нужна просто потому, что так сказали.
На мой взгляд, это самый омерзительный случай — страдают все: и те, кто пишет документацию – нудно, скучно, бессмысленно потраченные силы на соблюдение каких-нибудь ГОСТов, и те, кто потребляет ее – обязанность заказать и оплатить документацию по ГОСТу, потому что так надо.
Конечно, результаты такой деятельности частично оправданы, много полезных знаний сохраняется по итогам разработки, но порой вместе с таким же количеством бесполезных.
Служба эксплуатации, техническая поддержка и, конечно же, пользователи любят документацию. Чем больше написано в открытом источнике о способе решения задач или проблем, тем меньше они друг с другом взаимодействуют. Экономия ресурсов со всех сторон вполне очевидна.
Масштаб проекта – основная и единственная причина, по которой появляется необходимость внедрения документирования. Процесс масштабирования стоит рассматривать во всех возможных смыслах, касающихся разработки.
Есть сервис МойСклад и 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!)
Но это ерунда. Хуже, когда заказчик говорит: «Создали два разработчика. Уволить не могу, хотя почти ничего не делают, только по мелочи донастраивают. А с этой системой у нас уже и бухгалтерия интегрирована, и … Документация? Нет ее. А надо?.. Спасите-помогите»!
Проблемы с документацией в процессе разработки ПО были, есть и будут. Эта статья посвящена поиску момента, в который появляется необходимость ведения проектной документации и поможет принять решение, если у вас только начали появляться мысли об этом. Повествование сопровождается примерами из жизни МоегоСклада.
Что это за зверь — «документация»?
С чего начинается задача на разработку? С идеи. Чтобы что-то создать, нужно это представить в своей голове. Чтобы не потерять мысль, её лучше зафиксировать.
По сути, документирование — это процесс описания идеи от момента ее возникновения в сознании до выпуска результатов в релиз. А значит документировать мы начинаем в момент написания ТЗ, при описании задачи, без строгого формата, в картинках или на листе бумаги. Когда мы формализуем, как это должно работать.
Для кого документировать?
Если нет понимания, кому нужна проектная документация, то она не нужна. Возможно, прочитав эту статью чуть дальше, мнение может резко поменяться, но это не точно.
В первую очередь документация нужна команде разработки и заказчику.
Разработчик быстрее осознает, над чем он вообще трудится, спокойнее принимает «чужое наследство».
Тестировщик каждый раз не находит одни и те же ошибки, которые на самом деле уже стали особенностями реализации.
Для бизнес-заказчика наличие минимальной документации, описывающей изнутри его программный продукт, позволяет не быть в рабской зависимости у своих разработчиков или подрядчиков.
Иногда проектная документация нужна просто потому, что так сказали.
На мой взгляд, это самый омерзительный случай — страдают все: и те, кто пишет документацию – нудно, скучно, бессмысленно потраченные силы на соблюдение каких-нибудь ГОСТов, и те, кто потребляет ее – обязанность заказать и оплатить документацию по ГОСТу, потому что так надо.
Конечно, результаты такой деятельности частично оправданы, много полезных знаний сохраняется по итогам разработки, но порой вместе с таким же количеством бесполезных.
Служба эксплуатации, техническая поддержка и, конечно же, пользователи любят документацию. Чем больше написано в открытом источнике о способе решения задач или проблем, тем меньше они друг с другом взаимодействуют. Экономия ресурсов со всех сторон вполне очевидна.
Причины, по которым компании приходят к внедрению документирования
Масштаб проекта – основная и единственная причина, по которой появляется необходимость внедрения документирования. Процесс масштабирования стоит рассматривать во всех возможных смыслах, касающихся разработки.
Есть сервис МойСклад и 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!)
Julich71
Корректорское замечание. После изображений «Среднестатистическая автомастерская — Среднестатистический автомеханик» помещены два одинаковых куска текста (различаются только знаками препинания в последнем предложении).
katherine_a Автор
Благодарю! Поправила