Момент, когда проектная документация нужна

    Время идет, планета крутится, системы растут и развиваются, а я продолжаю слышать в кругах аналитиков сожаление: «Эх, пришел на проект, а тут никакой документации, смотрим в код».

    Но это ерунда. Хуже, когда заказчик говорит: «Создали два разработчика. Уволить не могу, хотя почти ничего не делают, только по мелочи донастраивают. А с этой системой у нас уже и бухгалтерия интегрирована, и … Документация? Нет ее. А надо?.. Спасите-помогите»!

    Проблемы с документацией в процессе разработки ПО были, есть и будут. Эта статья посвящена поиску момента, в который появляется необходимость ведения проектной документации и поможет принять решение, если у вас только начали появляться мысли об этом. Повествование сопровождается примерами из жизни МоегоСклада.



    Что это за зверь — «документация»?


    С чего начинается задача на разработку? С идеи. Чтобы что-то создать, нужно это представить в своей голове. Чтобы не потерять мысль, её лучше зафиксировать.

    По сути, документирование — это процесс описания идеи от момента ее возникновения в сознании до выпуска результатов в релиз. А значит документировать мы начинаем в момент написания ТЗ, при описании задачи, без строгого формата, в картинках или на листе бумаги. Когда мы формализуем, как это должно работать.

    Для кого документировать?


    Если нет понимания, кому нужна проектная документация, то она не нужна. Возможно, прочитав эту статью чуть дальше, мнение может резко поменяться, но это не точно.



    В первую очередь документация нужна команде разработки и заказчику.

    Разработчик быстрее осознает, над чем он вообще трудится, спокойнее принимает «чужое наследство».

    Тестировщик каждый раз не находит одни и те же ошибки, которые на самом деле уже стали особенностями реализации.

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

    Иногда проектная документация нужна просто потому, что так сказали.

    На мой взгляд, это самый омерзительный случай — страдают все: и те, кто пишет документацию – нудно, скучно, бессмысленно потраченные силы на соблюдение каких-нибудь ГОСТов, и те, кто потребляет ее – обязанность заказать и оплатить документацию по ГОСТу, потому что так надо.

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

    Служба эксплуатации, техническая поддержка и, конечно же, пользователи любят документацию. Чем больше написано в открытом источнике о способе решения задач или проблем, тем меньше они друг с другом взаимодействуют. Экономия ресурсов со всех сторон вполне очевидна.

    Причины, по которым компании приходят к внедрению документирования


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

    Есть сервис МойСклад и 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!)
    МойСклад
    Разрабатываем облачный сервис управления торговлей

    Комментарии 19

      0
      Корректорское замечание. После изображений «Среднестатистическая автомастерская — Среднестатистический автомеханик» помещены два одинаковых куска текста (различаются только знаками препинания в последнем предложении).
        0
        Благодарю! Поправила
        0

        Актуально. Исходя из своего опыта склонен считать, что разработка без документации или, что еще хуже, без задачи в трекере, должна быть отнесена к техническому долгу. С большой вероятностью это будет недостаточно продуманное решение, которое в потоке работы забудется. Когда настанет момент поддержки (как известно, в любом коде есть как минимум одна ошибка) придется долго и лихорадочно заниматься "археологией по коду".


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


        Шаблон описания задачи

        image


        Получается с переменным успехом, но, в целом, подход себя оправдывает.


        Для чего-то бо́льшего лучше сразу набросать и зафиксировать архитектуру.


        Пример фрагмента архитектуры

        image


        При наличии таких схем, к примеру, процесс "онбоардинга" существенно упрощается.

          0
          Если хотя бы в трекере оставить следы с описанием, что вообще было реализовано, то это уже хорошо. Я придерживаюсь позиции, что документация на систему должна храниться в предназначенном для этого месте — Confluencem Notion и т.п., а не в таск-трекере.

          Шаблон описания задачи — отличная практика! У нас в компании он тоже внедрен. Его его целевое назначение не сохранение документации, а точка входа в статью с документацией.
          Основное из шаблона:

          • бизнес-требования,
          • постановка задачи (кратко) со ссылкой на подробное описание реализации,
          • описание миграций данных,
          • рекомендации к тестированию,
          • о мониторинге и т.п.
            0
            Я придерживаюсь позиции, что документация на систему должна храниться в предназначенном для этого месте — Confluencem Notion и т.п., а не в таск-трекере

            А в чем преимущество такого подхода? Вот фрагмент "самодокументации" из одного моего проекта:
            image


            Каждая ссылка ведет на задачу, задачи оформлены по шаблону. Если нужно что-то вспомнить — заходишь в оглавление, открываешь задачу и читаешь. Для внутренней документации — самое то.

              0

              в том что не надо велосипеда как у вас.
              создал страницу, прикрепил к ней задачу, сделано (задача и все что было в ней: комменты, описания скрины и прочий шлак — все это забыто и умерло).
              а в конфе у вас осталась только дока, потому что все остальное больше не нужно.

                +2
                А зачем Вы вообще создаете шлак? Чтобы потом забыть? Странное занятие.
                Или что Вы понимаете под «шлаком»? И что такое у Вас «дока»?
          +1
          На мой взгляд, это самый омерзительный случай — страдают все: и те, кто пишет документацию – нудно, скучно, бессмысленно потраченные силы на соблюдение каких-нибудь ГОСТов, и те, кто потребляет ее – обязанность заказать и оплатить документацию по ГОСТу, потому что так надо.

          Если делать по ГОСТ "для галочки", то это, конечно, так себе удовольствие.


          Но вот если "с душой" :), с чувством, с толком, с расстановкой, то вполне полезные вещи можно обнаружить. Взять, к примеру, милейший документ ГОСТ 19.404-79 ПОЯСНИТЕЛЬНАЯ ЗАПИСКА.


          1.2. Пояснительная записка должна содержать следующие разделы:
          • введение;
          • назначение и область применения;
          • технические характеристики;
          • ожидаемые технико-экономические показатели;
          • источники, использованные при разработке.

          Чем плохо? Можно, конечно, сказать, что "ожидаемые технико-экономические показатели" это "фу", особенно "экономические...". Да все понятно, микросервисы наголо и помчались. Но разве не полезно понимать — а что же бизнес получит от этого всего?


          Ну и далее:


          2.3. Раздел «Технические характеристики» должен содержать следующие подразделы:
          • постановка задачи на разработку программы, описание применяемых математических >методов и, при необходимости, описание допущений и ограничений, связанных с выбранным математическим материалом;
          • описание алгоритма и (или) функционирования программы с обоснованием выбора схемы алгоритма решения задачи, возможные взаимодействия программы с другими программами;
          • описание и обоснование выбора метода организации входных и выходных данных;
          • описание и обоснование выбора состава технических и программных средств на основании проведенных расчетов и (или) анализов, распределение носителей данных, которые использует программа.

          Если это все заполнено кратко и по делу, то такая документация будет очень полезной.

            0
            Согласна. ГОСТ нужно использовать с душой и с умом.

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

              Если подойти к процессу документирования как к части процесса разработки, то обновление документации можно сделать нормой. Например, внедрив практику оформления отдельного сабтаска «Документирование» к задачам на разработку
                +1
                Далеко не все понимают, что документация — это тоже система, которая должна строиться по определенным принципам и отвечать требованиям большинства своих пользователей.

                Этому, как бы, должны учить. Как в проектировании бетонно-железных артефактов учат(?). Но в нашей индустрии привычки какие-то другие. Документация — а как получится, кто-нибудь как-нибудь напишет.

                  0
                  Этому, как бы, должны учить.

                  Поддерживаю!

                  Но пока это упорно игнорируется, особенно бизнес-заказчиками. Только опыт «наступить на грабли» заставляет немного задуматься.
                +1
                Спасибо автору за смелость: утверждать, что необходимо документировать разработку системы, сейчас непопулярно и даже очень непопулярно! Согласен с автором во всем! Кроме одного. На протяжении всей статьи автор оправдывается за это свое мнение. Видать очень велик страх нарваться на осуждение в комментариях. Поэтому Ваш вывод
                Процесс документирования нужен далеко не всегда и это нормально.
                это ошибка! Приведите пример и дайте разумное обоснование, когда документирование не нужно! Примеры отсутствия документирования и вообще проектирования есть, и, чем далее, тем более. Но разумного в этом ничего нет! И быть не может!
                Причины отсутствия документирования две:
                1) лень. И это простительно, т.к. в природе человека. На этот случай есть погоняло — руководитель проекта и грамотный заказчик;
                2) безграмотность, невежество разработчиков. Это уже непростительно. Лечится только рублем. Иногда даже через хозяйственный (арбитражный) суд.
                Выбирайте, если есть желание.
                Даже в самой простой доработке есть две стороны с противоположными интересами: заказчик и разработчик, даже, если они работают на одном предприятии. Любой проектный документ — это договор между ними. Если обе стороны добросовестны, то он может и не понадобится. А если результат неудовлетворительный?
                Поверьте старому разработчику — в программировании есть две самые большие проблемы:
                1. Добиться от заказчика вменяемого изложения требований.
                2. Доказать заказчику, что программа сделана в строгом соответствии с его требованиями.
                Проектируйте, господа, проектируйте! И будет вам счастье.
                Успехов!
                  0
                  Приведите пример и дайте разумное обоснование, когда документирование не нужно!

                  Если продукт свой, заказчика нет и нужно запустить быстро, без выделения времени на описание, то, например, встроенные комментарии в код спасают. Это нельзя назвать проектной документацией, потому что к ней не все имеют доступ, а только разработчики.

                  На протяжении всей статьи автор оправдывается за это свое мнение.

                  Главная мысль статьи — смотреть на масштаб проекта. Не всегда экономически целесообразно сразу выделять ресурс на документирование и заказчика не убедить.

                  Даже в самой простой доработке есть две стороны с противоположными интересами: заказчик и разработчик

                  Рассмотрим документирование требований — договор между заказчиком и разработчиком. Требования, конечно, тоже документация, но не всегда в том объеме, чтобы помочь разобраться — как работает система. К тому же, в ходе разработки, требования имеют свойство меняться и уточняться, не всегда эти изменения и уточнения фиксируются в том самом оригинале договора и знания теряются. Такая вот грустная практика до сих пор существует.

                    0
                    Если продукт свой, заказчика нет и нужно запустить быстро, без выделения времени на описание, то, например, встроенные комментарии в код спасают.
                    Заказчик есть всегда! Это не только функция, но и роль, которую может играть даже член команды проекта. Я уверен, что «заказчики» есть и Вашей команде, только Вы их таковыми не считаете. И зря. Можно специально назначать такого «заказчика» и увидите, что он значительно поднимет вам качество работы.
                    А комментарии в коде — это элемент стиля программирования, это отношение программиста к своему коллеге, которые возможно будет разгребать написанное. Относитесь к нему уважительно, и Вам будет приятно работать, да и, как знать, может через годик-другой самим придется разгребать свое творчество.
                    Главная мысль статьи — смотреть на масштаб проекта. Не всегда экономически целесообразно сразу выделять ресурс на документирование и заказчика не убедить.
                    Документирование — это не вопрос экономической целесообразности. Это вопрос качества работы команды проекта, и в этом вопросе надо не заказчика убеждать, а себя, если это еще не стало у вас нормой.
                    А качество, естественно, косвенно, но влияет и на экономику проекта, и очень даже часто, сильно влияет. И качество работы уж совсем не зависит от масштаба проекта. Как известно ложка дегтя может испортить бочку меда! Хотите долго задержаться на рынке — повышайте качество работы и даже на мелких проектах. Более того, беритесь за проекты, которые завалили ваши конкуренты. Это самая интересная и благодарная работа.
                    Требования, конечно, тоже документация, но не всегда в том объеме, чтобы помочь разобраться — как работает система. К тому же, в ходе разработки, требования имеют свойство меняться и уточняться...
                    Согласен. Часто заказчик сам не понимает чего хочет, но еще чаще, он не понимает возможностей автоматизации. Поэтому относитесь к требованиям заказчика, как к своим. Для этого есть прекрасный механизм, например, обследование бизнес-процессов заказчика. По результатам обследования вместе проведете оптимизацию и напишете новые требования и ТЗ. Тогда они уже не будут меняться и уточняться. А если и будут, то только совершенствоваться.
                    Такая вот грустная практика до сих пор существует.
                    Все в ваших руках и мозгах! Поверьте, проектирование — это не только интересно, но и весело! Особенно на незнакомом объекте. Нет ничего более интересного, чем процесс познания нового.
                    Но хорошее ТЗ, написанное совместно с заказчиком, это не только чувство удовлетворения от хорошо сделанной работы, но это и еще эффективное средство повышения производительности труда программиста — это его шпаргалка, или даже настольная книга до самого окончания проекта. Если будете писать такие ТЗ, то всей команде будет весело. И заказчик легче будет подписывать счета на оплату.
                    Проектируйте, господа, проектируйте!
                      0
                      Заказчик есть всегда!

                      Все так. В нашей компании есть роль заказчика, и он не один. Это владельцы продуктов — подсистем МоегоСклада.

                      Это вопрос качества работы команды проекта

                      В точку! Это можно добавить как один из положительных результатов по итогам внедрения документирования: требований, результатов проектирования и реализации.

                      требования и ТЗ. Тогда они уже не будут меняться и уточняться. А если и будут, то только совершенствоваться.

                      Тут еще можно добавить про уровни детализации. На этапе ТЗ с заказчиком, важно сделать проработку того, что видит пользователь, какие есть бизнес-правила и ограничения, и так далее. Все это — бизнес-требования. Они идут в основу ТЗ и это обычно то самое, что Заказчик осознанно читает и подписывает.

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

                      Убедить заказчика в том, что проектирование и документирование нужны — не сложно. Достаточно хотя бы задать вопрос: «Вы же потом планируете развиваться?». Но по неизвестным причинам я часто слышу: «У нас нет документации», «У нас нет времени на это». Почему за обеспечение качества не хотят браться? Подозрение, что экономят (конечно, ошибочно думают, что экономят!).

                      Зачем жертвовать качеством, строить странные процессы разработки, жить без группы тестирования и т.д., если это приводит к печальным последствиям — огромнейшая тема для обсуждения! Ей нужно посвящать отдельную статью. Но такое сегодня все еще есть!

                      Я безмерно восхищаюсь, что в нашем продукте обеспечивают качество, следят за этим и стремятся к постоянному совершенствованию процесса разработки.

                      Но есть рынок труда. Есть другие компании и их сотрудники, с которыми общаешься на конференциях, собеседованиях, в тематических чатах, и видишь, что в их компаниях такой задачи как «документирование» нет, но им этого явно не хватает. Людям не хватает уверенности и аргументов для убеждения своего заказчика, что надо строить процессы правильно!

                      До последней строки поддерживаю Ваш комментарий. Надеюсь, что много читателей доберутся до него и извлекут для себя убедительных аргументов: «Документация нужна»!
                  0
                  Было бы уместно упомянуть MIL-STD-498, в котором работают разработчики промышленного софта (западные). Вот уж точно ничего не забудешь
                  Произвольный кусок из System Design Description
                  c. Characteristics of individual data elements that the interfacing entity(ies) will provide, store,
                  send, access, receive, etc., such as:
                  1) Names/identifiers
                  Project-unique identifier
                  Non-technical (natural-language) name
                  DoD standard data element name
                  Technical name (e.g., variable or field name in code or database)
                  Abbreviation or synonymous names
                  Data type (alphanumeric, integer, etc.)
                  Size and format (such as length and punctuation of a character string)
                  Units of measurement (such as meters, dollars, nanoseconds)
                  Range or enumeration of possible values (such as 0-99)
                  Accuracy (how correct) and precision (number of significant digits)
                  Priority, timing, frequency, volume, sequencing, and other constraints, such as whether
                  the data element may be updated and whether business rules apply
                  8) Security and privacy constraints
                  9) Sources (setting/sending entities) and recipients (using/receiving entities)
                  d. Characteristics of data element assemblies (records, messages, files, arrays, displays,
                  reports, etc.) that the interfacing entity(ies) will provide, store, send, access, receive, etc.,
                  such as:
                  1) Names/identifiers
                  Project-unique identifier
                  Non-technical (natural language) name
                  Technical name (e.g., record or data structure name in code or database)
                  Abbreviations or synonymous namesSoftware Design Description (SDD)
                  (PDF version)
                  DI-IPSC-81435
                  2) Data elements in the assembly and their structure (number, order, grouping)
                  3) Medium (such as disk) and structure of data elements/assemblies on the medium
                  4) Visual and auditory characteristics of displays and other outputs (such as colors,
                  layouts, fonts, icons and other display elements, beeps, lights)
                  5) Relationships among assemblies, such as sorting/access characteristics
                  6) Priority, timing, frequency, volume, sequencing, and other constraints, such as whether
                  the assembly may be updated and whether business rules apply
                  7) Security and privacy constraints
                  8) Sources (setting/sending entities) and recipients (using/receiving entities)
                  e. Characteristics of communication methods that the interfacing entity(ies) will use for the
                  interface, such as:
                  f.
                  Project-unique identifier(s)
                  Communication links/bands/frequencies/media and their characteristics
                  Message formatting
                  Flow control (such as sequence numbering and buffer allocation)
                  Data transfer rate, whether periodic/aperiodic, and interval between transfers
                  Routing, addressing, and naming conventions
                  Transmission services, including priority and grade
                  Safety/security/privacy considerations, such as encryption, user authentication,
                  compartmentalization, and auditing
                  Characteristics of protocols the interfacing entity(ies) will use for the interface, such as:
                  Project-unique identifier(s)
                  Priority/layer of the protocol
                  Packeting, including fragmentation and reassembly, routing, and addressing
                  Legality checks, error control, and recovery procedures
                  Synchronization, including connection establishment, maintenance, termination
                  Status, identification, and any other reporting features
                    0

                    Из собственного опыта. Как бэкенд-разработчик на проекте веду:


                    1. Покрытие кода комментариями JavaDoc для коллег-бэкендеров.
                    2. Текстовое описание бизнес-логики в Confluence, для всех разработчиков на проекте.
                    3. И swagger на dev-сервере, чтобы пощупать методы и описать их request-response.

                    Да, это усилия, но таковы правила компании. Не могу сказать, что меня это напрягает.

                    Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.

                    Самое читаемое