Что такое разработка проектной документации и что в неё входит
Чтобы рассчитать все затраты на реализацию проекта, необходимо составить определённый список затрат. Так же, помимо расчётов, нужно расписать предметную область, цели и задачи создания и разработки проекта. Сегодня мы подробно поговорим о процессе разработки проектной документации, что это такое, как её правильно составить и что в неё входит.
Разработка проектной документации: что это
Перед началом разработки проектной документации, необходимо знать, что это такое. Вообще, сама по себе, проектная или проектно-сметная документация, как её ещё называют – это перечень документов, в которых отражается вся структура проекта. Его цели, задачи, возможные трудности и пути их решения. В принципе, сам процесс составления можно сравнить с техническим заданием на создание сайта, так как в нём будет так же подробно описываться любая мелочь.
Разработка проектной документации – это один из главных этапов реализации проекта. В них отражаются не только расчёты, которые приведены в виде графиков и формул, но и различные решения сложностей на пути воплощения проекта в полномасштабный объём. Важную роль сметные документы играют в проектировании строительства какого-либо объекта, особенно, если речь идёт о масштабных построениях.
Состав проектной документации. Зачем нужен проект дома? Читай описание.
Ведь, чтобы верно рассчитать все параметры здания, расположить его в таком месте, чтобы природные и климатические условия не наносили сооружению ущерб, необходимо всё это сначала проработать на бумаге. Это всё равно что составить бизнес-план, то есть с помощью наглядного примера выявить проблемную область и разработать пути решения.
Кто занимается разработкой проектной документации
Не многие представляют, кто и где занимается разработкой проектной документации. На самом деле, на этот вопрос есть два ответа. Первый, это когда сами участники-разработчики своими силами, читая литературу про экономику и черчение, пытаются составить смету, сделать графические чертежи намеченного продукта. Во втором случае, эта работа предоставляется профессионалам.
Да, есть специальные агентства, или отдельный, специально обученный человек, который профессионально занимается составлением смет, сводкой данных и черчением модели готового продукта, который получится в итоге. На самом деле, подобное занятие – это сложный процесс, именно поэтому такая услуга стоит недёшево, если говорить конкретно, то цены SEO продвижение сайтов в месяц не на много выше, чем стоимость разработки документов для проекта.
Конечно, в обращении к специалистам есть своим плюсы. Во-первых, это сокращение времени, которые может уйти на обучение всем тонкостям расчётов и умение составлять чертёж. Так же, документация будет разработана максимально точно, что позволит избежать просчётов, которые в последствии могут стать роковой ошибкой. Для тех, кто выделил на создание самого проекта конкретную сумму, может себе это позволить, тем самым повысить вероятность в том, как получить финансирование проекта, и компенсировать свои затраты.
Что входит в разработку проектной документации
Всё, что входит в разработку проектной документации, прописано в соответствующем документе, а точнее, в Постановлении Правительства РФ от 16 февраля 2008 г. N 87 «О составе разделов проектной документации и требования к их содержанию». Согласно этим требованиям, в составе проектных документов должно присутствовать две части: текстовая и графическая.
В текстовой части должно содержаться всё, что касается объекта, то есть основные сведения Это и подробное описание процесса разработки, и приложения в виде нормативно-правовых актов, регламентов и гостов, а так же пояснительные записки и сама смета. Так же, в рамках теоретической части будут описаны различные проектные решения, связанные с размещения объекта, так же затрат на оборудование и возможные дополнительные инвестирования в проект.
К графическому материалу, относятся чертежи, содержащие наглядное конструирования концептуальных моделей, с помощью которых и выявляют проблемные области и анализируют сущность объекта. Вместе с чертежом, как правило, прилагается пояснительная записка, содержащая описание анализа, которое обосновывает принятия различных архитектурных решений. В ней так же описываются меры безопасности работ, которые будут проводиться в рамках реализации проекта.
Так же, своеобразным дополнением в проектной документации присутствует ещё и экономическая часть. Логично догадаться, что она будет содержать все расчёты, связанные с затратами на проект, а так же обосновывающее описание, по которому нужно будет производить финансирование и дальнейшее инвестирование.
На самом деле, разработка проектной документации – долгий и кропотливый процесс. Его основная цель – максимально точно представить макет проекта, точнее объекта проектирования, рассчитать все финансовые затраты, а так же обосновать решения, связанные с проектированием и конструированием той или иной модели.
Ответственный за составление документов проекта берёт на себя огромную ответственность за весь процесс реализации. Так как, в отличие от специалиста по продвижению сайта в топ 3 Яндекса, разработчик проектной документации отвечает за безопасность, надёжность и конструктивность всего процесса.
ИсточникРабочий проект и проектная документация
Рабочий проект (РП) представляет собой технический документ, в котором отображаются все необходимые для реализации строительства данные и технические расчеты.
Этот документ позволяет инженерам и строителям сразу понять, как и чем следует выполнять работу, параметры и габариты объектов, их характеристики и многие другие параметры будущего здания. Этого достаточно, чтобы приступить к строительным работам.
Цели и порядок разработки проектной и рабочей документации в составе проекта системы пожарной безопасности объекта
В общем случае для начала строительства серьезного объекта необходимо получить разрешение на строительство. А для этого необходимо пройти процедуру государственной экспертизы проектов (если объект подлежит таковой). Заказчик может и по собственной инициативе направить проектную документацию на экспертизу (это не обязывает органы государственной экспертизы ее проводить).
Экспертизу проходит именно проектная документация, включающая в себя графическую и текстовую часть, содержащие основные (принципиальные) технические решения. Экспертная организация, не вдаваясь в подробности, оценивает техническую возможность внедрения системы и соответствие принятых проектных решений требованиям законодательства и нормативных документов, после чего отправляет проектную документацию на доработку или выдает положительное заключение.
После этого наступает этап детальной проработки проектных решений — подготовки пакета рабочей документации, по которой будет создаваться запроектированная система или строиться объект капитального строительства. Правда, часть 2.1 статьи 48 «Градостроительного Кодекса РФ» не запрещает подготавливать проектную и рабочую документацию одновременно.
Так выглядит правильный процесс проектирования. Но зачастую все обстоит несколько иначе. Обращаем внимание читателя на то, что далее будет описано каким образом, нередко поступают проектировщики противопожарных систем в процессе разработки проектов для существующих и преимущественно небольших зданий.
Проектирование систем противопожарной защиты: состав проектной документации
Проектирование систем противопожарной защиты
Вопреки предусмотренному №87-ППРФ алгоритму действий, проектирование начинается с разработки рабочей документации. И только потом, в случае необходимости, на ее основе создается проектная документация. Это делается в целях экономии трудовых и временных затрат. Кроме того, как правило, без детальной проработки рабочей документации невозможно выполнить необходимые расчеты, предусмотренные пунктом 3 «Положения о составе разделов проектной документации и требованиях к их содержанию». Во многом описанный порядок действий обусловлен спецификой объектов — он целесообразен именно для отдельно разрабатываемых систем автоматической противопожарной защиты существующих зданий.
Перед тем как взяться за рабочую документацию, необходимо изучить «Техническое задание на проектирование», обследовать объект защиты, на который разрабатывается система, согласовать с заказчиком конечный результат, определиться, на каком оборудовании будут построены системы, какие функции они будут выполнять, где будут размещаться, как будут выглядеть и т.п. Имея на руках эти данные, можно приступать к подготовке рабочей документации.
Безусловно, проектировщик должен твердо знать нормы и правила проектирования систем пожарной сигнализации, изложенные в нормативных правовых актах и нормативных документах по пожарной безопасности. Но загвоздка в том, что состав проектной документации определен №87-ППРФ , а вот состав рабочей документации, во всяком случае, на системы пожарной автоматики, не определен ничем.
Только в пункте 4.7 ГОСТ Р 59638-2021 «Системы пожарной сигнализации. Руководство по проектированию, монтажу, техническому обслуживанию и ремонту. Методы испытаний на работоспособность» (далее – ГОСТ Р 59638-2021) приведен перечень прилагаемых документов, которые должна включать в себя рабочая документация систем пожарной сигнализации:
алгоритм работы систем пожарной сигнализации (допускается приводить в составе пояснительной записки), который может быть изложен в графическом, табличном, текстовом виде или комбинировано;
иные документы, предусмотренные заданием на проектирование или по согласованию с заказчиком.
Помимо перечисленного отдельным приложением к рабочей документации следует приводить «Кабельный журнал», содержащий сведения о назначении и длине кабельных линий, марке кабелей и способе их прокладки, напряжении в них.
Основой рабочей документации являются «Рабочие чертежи», на которых приводятся поэтажные планы расстановки оборудования и прокладки сетей, схемы внешних соединений и подключений приборов, структурные схемы. При необходимости комплект рабочих чертежей может быть дополнен и другими материалами. Согласно пункта 4.6 ГОСТ Р 59638-2021 рабочая документация должна быть оформлена в соответствии с ГОСТ Р 21.101.
Вот, собственно, и все. Из готовой рабочей документации можно делать выборку для раздела 9 «Мероприятия по обеспечению пожарной безопасности» или сформировать собственный комплект проектной документации.
Резюмируя изложенное, можно сказать, что проектная и рабочая документация не синонимы и разрабатываются для разных целей. Они отличаются по своему составу и содержанию, при этом рабочая документация основывается на проектной документации и содержит детальную проработку мер по реализации решений, принятых в ней.
Сравнительный анализ СП 10.13130.2020 и СП 10.13130.2009: изменения в области применения, терминологии и классификации внутреннего противопожарного водопровода В настоящее время при проектировании и реконструкции внутреннего противопожарного водопровода применяется Свод правил СП 10.13130.2009 «Системы противопожарной защиты. Внутренний противопожарный водопровод.
Требования пожарной безопасности», утвержденный приказом МЧС России от 25 марта 2009 года № 180. Однако уже с 27 января 2021 года вступит в силу приказ МЧС России от 27 июля 2020 года № 559, в соответствии с которым СП 10.13130.2009 признается утратившим силу. В действие вводится новый Свод правил СП 10.13130.2020 «Системы противопожарной защиты. Внутренний противопожарный водопровод. Требования пожарной безопасности» читать полностью
Функции документации по нормативно-правовой базе
Проектная и рабочая документация содержит в себе важную для будущего строительства информацию. Она нужна не только потому, что это требование законодательных актов (Постановления № 87 от 16.02.08 г., где прописаны основные определения и требования).
Правильно составленные разделы строительного проекта позволяют получить качественный результат строительства, ремонта или реконструкции. Определяет общую стоимость расходов, которые потребуются на объект, и дает возможность оптимизировать их благодаря точным расчетам. Строительный объект становится более привлекательным для инвесторов. Строительство должно завершиться в точно установленные сроки.
Чем отличаются пакеты документов
Если объяснить отличия межу наборами документов простыми словами, без сложной терминологии, то можно прийти к следующим выводам:
- Основой любого инвестиционного проекта является именно проектная документация, которая может включать в себя графическую и текстовую часть. В ней указаны самые главные технические решения, доказывающие как техническую возможность, так и экономическую целесообразность внедрения конкретного инвестиционного проекта. Именно этот пакет документов подается застройщиком на государственную экспертизу и утверждается после ее положительного заключения. Исключение составляет только строительство индивидуальных жилых домов. Следует отметить, что исключительно по проектным документам сооружение возвести нельзя, так как они носят относительно общий характер, не содержат всех необходимых деталей и спецификаций.
- Для того же, чтобы строительная организация могла качественно выполнить свою работу, ей потребуется более детально описанное задание: что конкретно, как и из каких материалов строить. Эти данные содержатся в рабочей документации, которая детализирует все решения проектировщиков и состоит из текстового описания работ и многочисленных схем, чертежей, графиков, спецификации всех компонентов и готовых изделий. Объем информации должен быть достаточен для проведения строительно-монтажных работ, обеспечения стройки требуемым количеством сырья, оборудования, материалов и готовых изделий, рабочих и инженерных кадров.
Закономерно возникает вопрос: если все эти действия составляют проектный этап, то зачем он был разделен на две части. Ответом может быть то, что таким образом законодатель хотел ускорить стартовую фазу инвестиционного цикла. Для получения разрешения на ведение строительных работ, вполне хватит качественной проектной документации, которую можно экспертно изучить, не вдаваясь в излишние детали. После проведения государственной экспертизы и исправления всех замечаний, можно прорабатывать рабочие моменты.
Во время проведения мероприятий строительного контроля проверяется соответствие выполненных работ требованиям как проектной, так и изготовленной на ее основе рабочей документации. Кроме того, изучается соответствие градостроительному плану, инженерным изысканиям и техническим регламентам. Застройщик и подрядчик в равной степени несут ответственность за соблюдением в процессе капитального строительства норм законодательства, проектных и рабочих документов.
Поскольку четкой последовательности изготовления указанных двух пакетов документов не определено, то можно выделить такие виды стадийности проведения проектирования:
- Одностадийное. Оба пакета разрабатываются параллельно, это то, что раньше носило название «рабочий проект», т.е. утверждаемая часть с рабочими приложениями.
- Двухстадийное. Происходит последовательная подготовка пакетов. Приблизительно соответствует ранее действовавшим понятиям «ТЭО» и «рабочая документация».
- Трехстадийное. Актуально только для объектов III (индивидуальные проекты), IV и V категорий сложности. Кроме вышеозначенных фаз, включает еще предпроектное предложение (FEED).
Требование только одно – разработка рабочей документации не может предшествовать проектной.
Что такое проектная документация?
В отличие от рабочего проекта, проектная документация (ПД) — это больше концепция, нежели графики и цифры. Она представляет собой целый комплекс различных документов с детализацией в 2D и 3D будущего здания, описания его назначения, особенностей концепции и архитектуры, методах строительства.
Этот документ позволяет лучше понять, как должен будет выглядеть проект визуально, какие материалы должны приобретаться и использоваться, какие строительные нормы и ГОСТы должны выполняться. Кроме того, в нем заранее рассчитывается стоимость всех будущих работ, где каждый этап расписан по отдельности с указанием окончания сроков выполнения.
С чего начать составление проектной документации
Перед тем как приступать к созданию проектной документации и разработке первых вайрфреймов, изучите рынок. Даже если это напрямую не прописано в договоре с клиентом, сделайте базовый ресерч по основным конкурентам: как работает интерфейс, какие страницы есть, как расположено меню. Выпишите опции и функционал, которого нет у вашего заказчика. Обсудите их вместе, акцентируя внимание на следующих аспектах:
1. Хочет ли клиент добавить на сайт такую же функцию?
Всегда помните, что заказчик не должен быть силен в технических терминах. Ваша задача на данном этапе — объяснить ему, какую задачу с точки зрения бизнеса решает каждый функциональный модуль, который есть на сайте у конкурентов.
2. Нужна ли бизнесу клиента данная функция?
Все игроки FinTech России — по ссылке
Поговорите с клиентом о его ожиданиях от изменений сайта: нужен ли этот функциональный модуль с точки зрения продаж, улучшит ли он качество сервиса, соответствует ли набору доступных услуг? Например, если у вашего заказчика интернет-магазин, где доставка осуществляется только через курьерскую службу, то ему точно не нужен модуль с вариантами выбора пунктов самовывоза на карте. Даже если он есть у всех конкурентов.
3. Насколько сильно добавление этой функции повлияет на смету и сроки проекта?
Еще на этапе обсуждения дополнительного функционала расскажите клиенту о том, как это может повлиять на ход проекта. Например, если заказчик хочет сделать личный кабинет, как у конкурентов, объясните, что бюджет на реализацию этого блока может быть больше, чем сумма всего проекта на текущий момент, а сроки увеличатся в несколько раз.
Не забудьте проверить на прочность и текущий сайт вашего заказчика. Мы для этого часто привлекаем асессоров, то есть людей, которые тестируют сайт по нашей просьбе. Если будете делать такой вариант аудита, внимательно отнеситесь к подбору людей. Если это интернет-магазин женской косметики, нужно искать именно тех, кто будет его целевой аудиторией.
Разработайте для них анкету или опросник, которую они должны будут заполнить после использования ресурса. Это позволит выявить баги, слабые стороны, недостающие функциональные модули. Проанализируйте полученные данные и сформируйте из них интуитивно понятную схему, которая станет частью проектной документации.
Схематичная визуализация результатов асессорского аудита
Что важнее?
Оба документа одинаково важны. Хотя, основным для любого инвестиционного проекта является, пожалуй, проектная документация. Во-первых она более досконально проработана, она объемнее, поскольку включает в себя огромное количество листов графической и текстовой информации. Во-вторых, с таким документом намного проще привлекать деньги банков и инвесторов.
Благодаря комплексу проектной документации у инвесторов уже не возникает вопросов насчет инженерных и технический решений строительства будущего здания, а также складывается понимание как будет выглядеть будущий проект. В дальнейшем, комплекс всех этих документов отдается на гос. экспертизу и после одобрения там приступают к его реализации.
С другой стороны, нужно учитывать, что подготовка проектной документации — это долгая и кропотливая процедура. И если для заказчика важны сроки и достаточно простого описания какие материалы использовать, как что выполнять и к какому сроку, можно обойтись разработкой рабочего проекта. Все работы здесь описываются в текстовом формате, для них не нужны сложные графика, чертежи и визуализация, поэтому документы готовятся быстро и заказчик может сразу же приступать к строительным работам.
Особенности проектной документации и стадии проектирования
Чтобы понять, чем отличается рабочая документация от проектной, стоит более подробно остановиться на ключевых особенностях каждой из них. Проект строительства объекта включает функциональные, архитектурные, технические, инженерные решения. Все они отражаются в графическом и текстовом форматах.
Если говорить о том, что включает проектная документация и рабочая документация, отличия состоят в детализации. Проектная документация включает более широкий спектр информации об объекте, но прорабатывается с невысокой степенью детализации, главное она должна пройти государственную или негосударственную экспертизу на соответствие строительным нормам и обеспечению безопасности. После чего на ее основе разрабатывается рабочая документация.
Стадии проектной документации утверждены нормативно-правовыми актами (ПП РФ №87), состоят из 12 разделов.
- Общая пояснительная записка. Включает в себя исходную информацию о строительстве на основании существующего договора, заключение по проведенным инженерным изысканиям, правоустанавливающую информацию, зарегистрированный план земельного участка, информацию о назначении строительного объекта, технические условия, разрешающие документы.
- Схема планировочной организации земельного участка, на котором планируется разместить объект.
- Архитектурные решения. Это графическая и текстовая часть, которая содержит поэтажные планы здания, цветовое оформление фасадов, его внешний вид. Также здесь указывают решения по отделке, композиционные приемы, художественные и пространственные решения. Включено описание архитектуры, строительных и художественно-декоративных мероприятий.
- Конструктивные и объемно-планировочные решения. Раздел содержит конструктивные схемы, технические решения, обусловленные безопасностью конструкции. Описывается строительство подземной и надземной части, вспомогательных конструкций. Здесь же представлены графические материалы конструкций: планы стен, колонн, перекрытий, покрытий, фундамента и пр.
- Информация об инженерно-техническом обеспечении. Сюда относится система электроснабжения, система водоснабжения, система водоотведения, система отопления, система вентиляции и прочие инженерные сети.
- Проект производства работ, который включает информацию по организации строительной площадки, транспортную обеспеченность, перечень требуемых специалистов, последовательность производства работ. Графически изображается календарный и генеральный план строительства.
- Проектные решения по демонтажу сооружений — в случае необходимости, если требуется расчистить участок под будущую застройку.
- Обязательно указываются принятые меры по охране окружающей среды.
- Разрабатываются в обязательном порядке противопожарные мероприятия.
- Мероприятия, обеспечивающие доступность объекта для инвалидов и людей с ограниченными возможностями.
- Подробный сводный сметный расчет строительства.
- Другие требуемые документы, учитывающие особенности строительного производства.
Разработка проектной и рабочей документации может выполняться как параллельно, так и последовательно. Но в любом случае рабочая документация, исходя из Градкодекса, не может быть выпущена раньше проектной документации, во всяком случае ее легитимность будет под вопросом.
С точки зрения стоимости проектирования соотношение в процентах между стадями Р и П будет составлять 60% к 40% соответственно. Разработка рабочей документации позволяет детализировать информацию, подготовить ее для строительно-монтажных работ.
ИсточникДокументация в порядке
Пост о том, зачем и как аккуратно вести проектную документацию, даже если у вас Agile. Делюсь перечнем и структурой полезных документов и рекомендациями по работе с ними.
Речь пойдет в основном о внутренних документах, которые обычно никто не просит писать, но которые на самом деле нужны команде.
Небольшое лирическое отступление про то, что меня вдохновило на написание этого текста:
Теория разбитых окон
В криминологии есть так называемая теория разбитых окон: «Если в здании разбито одно стекло и никто его не заменяет, то через некоторое время в этом здании не останется ни одного целого окна». То есть, согласно теории, если порядок не поддерживается — люди охотнее его нарушают и не следуют правилам.
Теорию подтверждают эксперименты социологов из Нидерландов. В одном из них ученые приклеивали к рулям припаркованных велосипедов рекламные буклеты и убирали из окрестности все урны. При этом на стене рядом с велосипедами висело заметное объявление о запрете граффити. Для экспериментальной группы исследователи обеспечили сплошь разрисованную граффити стену, а для контрольной — чистую. В результате, у чистой стены выбросили на улицу или перевесили флаеры на чужой велосипед 25% группы из 77 человек, а у раскрашенной — 69%.
Считаю, что принцип теории можно распространить практически на все сферы жизни человека: чистота и порядок провоцируют на созидание и продуктивность, убирают элементы хаоса и отвлекающие факторы. Однако, конечно, лучше оставлять пространство для творчества и не сковывать себя абсолютной “идеальностью”.
При разработке ИТ-систем мне кажется очень важным поддерживать порядок в документации. Это и есть та самая “стена”, на фоне которой разворачивается проектная жизнь — на нее смотрят и делают выводы, что это за проект и как там все работает.
Зачем писать
Бывают проекты и без документации — но скорее всего так получилось не от хорошей жизни, либо никто из участников не знает, что “так можно было”.
Обоснованность наличия документации — отдельная тема, об этом писали, например, здесь.
Если коротко — то “без бумажки ты букашка”. Наша память обманчива и недолговечна. Завтрашний ты обманешь себя сегодняшнего или наоборот. Придет новый человек или уйдет старый — каждый такой финт будет стоить вам дорого. Без общей картины вы будете заниматься микроменеджментом и разработкой того, что уже кем-то сделано, но он забыл вам об этом сказать.
Будете делать петли и вставлять друг другу палки в колеса. А через полгода мучительно вспоминать, зачем нужен этот огромный кусок кода, который все тормозит. И это даже не касаясь кейса, когда вы заказали разработку на стороне.
Что писать
Сложно представить проект, на котором документация не нужна совсем. Другой вопрос, что она может быть разного формата и в разных объемах, покрывать разные аспекты системы.
Например, на старте проекта с гибкой методологией велика вероятность, что все еще раз 5 поменяется до момента внедрения. Поэтому подробное техническое описание может быть лишней тратой времени. А вот позитивный сценарий — на какие кнопки в каком порядке пользователь нажимает, какие данные вводит — нужен всем членам команды. И при частых его изменениях особенно важно, чтобы у всех было единое понимание текущей версии процесса.
Легче кому-то одному потратить пару часов на документирование, чем всей команде постоянно проверять свою память.
То есть даже когда обстоятельства не в пользу полноценного описания системы и вы работаете в “Agile”-режиме — важно понимать, что какая-то документация существенно облегчит процесс разработки и принесет много пользы .
Как выбрать то, что нужно документировать — дело каждого проекта. Приведу структуру и состав документации, которые считаю полезными.
Необходимый минимум
На мой взгляд документы, которые важны практически на любом проекте, это:
Документ-маршрутизатор
Место, откуда можно добраться до всех артефактов проекта. Это может быть страница в Confluence, пространство Notion или просто Google-документ. Важно создать единую точку входа — пусть там будут только ссылки на разные инструменты и источники, но вам не придется запоминать пути поиска нужного файла.
Артефакты проектных процессов
Флоу процесса разработки, статусная модель задач, доски с беклогом, план-график проекта, список нужных контактов и пр. Наличие такой документации налаживает процесс работы и делает его более комфортным. А также сильно разгружает аналитика/менеджера/тимлида и всех, кого волнует выполнение задач и сроки.
Глоссарий
Приводит всех участников работ к одному понятийному полю. Особенно полезен там, где много специальных терминов или разночтений. На некоторых проектах достаточно всего нескольких определений, но полезно все же их зафиксировать.
Артефакты бизнес-потребности и бизнес-процесса
Agile-манифест гласит: “Работающий продукт важнее исчерпывающей документации”. Но нельзя разработать работающий “как надо” продукт без четкого понимания, что же мы все-таки делаем и зачем. Бизнес-требования, схема процесса или просто письмо с постановкой от заказчика — что-то должно быть.
Концептуальная модель системы
Описание основных сущностей, верхнеуровневая функциональность и взаимодействие с другими системами.
Используйте IDEF0, «дорожки» BPMN, просто схему или текстовый перечень — главное обозначить принцип работы вашей системы.
Классы пользователей и уровни доступа
Такая памятка очень поможет при разработке требований — ведь всегда надо понимать, для кого и что делается. А путаница и в итоге неверный доступ — потенциально большие проблемы.
Cценарии использования
Даже если вы не используете этот инструмент для разработки требований — какой-то сценарий работы системы у вас есть. Это может быть инструкция для пользователей или тех. поддержки. Или последовательность вызовов с параметрами, если речь идет о взаимодействии систем.
Логика работы системы
По коду или БД не всегда получается понять смысл функционала. Например, формула расчета стоимости скорее всего задается бизнес-правилами, о которых коду ничего не известно.
Эти данные так или иначе передаются разработчикам при постановке задачи. Удобно сразу их записывать в виде читаемого документа, а в задачах вставлять только ссылки на место в этом документе. А если в тот же документ прикреплять тест-кейсы — будет совсем красиво.
Описание АПИ
Да пребудет с нами swagger и стандартный формат ответа методов. Если с вами интегрируются внешние компании — не обойтись и без подробного описания параметров.
Тестовые данные
Среды, учетные записи и все, что нужно, чтобы не сводить с ума тестировщика однообразными вопросами.
Ограничения/нефункциональные требования
Вы договорились, что рассчитываете максимум на 100 пользователей? Делаете импорт справочников раз в сутки в час ночи? Внешняя система не умеет принимать какие-то значения? Сделайте приятно себе в будущем — запишите все эти детали.
Другие типы документов
Потребность в некоторых документах возникает вариативно, в зависимости от особенностей проекта:
Архитектура системы
Иногда необходимо детальное описание сервисов и их взаимодействия. Например, если сервисов несколько и они взаимосвязаны, или если архитектура микросервисная.
Требования к данным
Логическая модель, требования к составу и формату данных, особенности работы с ними и пр. Всё это не всегда покрывается характеристиками БД — в таком случае полезно зафиксировать их в отдельном документе.
Сюда же можно добавить соглашения о формате БД — принципы наименования таблиц и атрибутов, используемые типы данных и пр.
UX/UI макеты и прототипы
Их лучше сразу собирать в одном известном всем месте и держать в актуальном состоянии.
С чехардой в макетах разбираться потом очень сложно. Просто представьте, что у вас хотя бы 3 экрана и у каждого хотя бы по 5 состояний. И аналитик, дизайнер и разработчики смотрят каждый в свой проект в фигме.
Описание интеграций
Протоколы интеграций, спецификации АПИ, процессы и потоки данных и всё, что необходимо для избежания недоразумений при взаимодействии с другими системами.
Безопасность
В целом параметры безопасности могут быть описаны вместе с доступами или нефункциональными требованиями, либо же наследоваться от общего контура ИТ компании. Но бывают системы с приоритетом или особым подходом к этой характеристике.
Внешняя документация
Документы для пользователей, партнеров, надзорных органов и прочие артефакты, которыми система общается с внешним миром.
Не трудно заметить, что бОльшая часть перечисленной информации скорее всего на проекте уже есть. Но она может быть разбросана по сохраненным сообщениям, личным папкам, письмам и прочему открытому космосу. Собрать это в единую структуру и оформить — не так долго, но эта работа может заметно сократить издержки на лишние вопросы, забытые задачи, кривой функционал и прочие неприятные факторы.
Как писать
Несколько инсайтов о работе с документацией:
Не забывайте про актуальность
Стоит писать только ту документацию, которую вы сможете поддерживать в актуальном состоянии.
При отсутствии описания люди начнут общаться друг с другом и у них есть шанс добраться до истины. При неактуальной документации — все будут на нее смотреть и делать неправильно.
Неоформленные артефакты — тоже документация
Удобно складывать в одно место те артефакты, которые нет возможности обработать и хорошо оформить.
Например, письма с договоренностями, примеры данных, ссылки и пр. Иначе вы скорее всего просто забудете, что такое когда-то было. Ну и в случае, если вдруг потребуется подтвердить какое-то согласование — не придется тратить час на поиск нужного письма в почтовом клиенте.
Растите культуру документирования в команде
Не обязательно всё должен документировать один человек, особенно если в команде нет специальной роли для этого. Даже не технические писатели умеют складывать ссылки в нужное место, писать чек-листы, комментировать макеты и прочее.
Важно договориться, как такая документация будет поддерживаться.
Комментарии в коде не всегда спасают
Структура кода не обязана повторять структуру процесса/функционала и, тем более, бизнес- и пользовательских требований. Поэтому из кода можно понять «как» работает система, но на вопросы «зачем?», «почему?» и «как должна?» отвечает именно проектная документация.
Планируйте и декомпозируйте работу с документацией
Документирование — это задача, которую легко разбить на небольшие отрезки времени и “размазать” по спринту.
Когда-то я бронировала в календаре последние 2 часа пятницы на составление/актуализацию документации. Принимать решения в это время опасно, к тому же эта деятельность помогает подвести итоги рабочей недели и запланировать следующую.
Закрывайте техдолг
При введении функционала в эксплуатацию важно выделить время на дооформление хвостов. Иначе не видать спокойной поддержки и доработки системы.
Понять, чего не хватает, просто: представьте, что вы приходите на этот проект сейчас, и никто из предыдущей команды с вами поговорить не может.
Больше схем и диаграмм
Визуальная информация воспринимается легче и быстрее, лучше запоминается. Чем больше данных вы представите графически — тем доступнее и короче будет документация.
Поможет изучение графических нотаций и UML, практика их применения, а также замечательная книга «Говори на языке диаграмм».
Учитесь писать нехудожественные тексты
Навык написания текстов сильно ускоряет процесс документирования и повышает его качество. Рекомендую использовать https://glvrd.ru. Плюс по возможности почитать «Пиши, сокращай» и «Бизнес-копирайтинг». Так и работа быстрее пойдет, и тексты станут понятнее и приятнее.
Как итог
Не обязательно подробно документировать всё, или хотя бы выполнять «необходимый минимум» из этой статьи. Всегда полезно сверять часы с реальностью и понимать — что действительно нужно и поможет достичь цели.
Но важно знать, какие есть инструменты и практики и как это делают в идеальном мире. Тогда вы поймете, на чем основывать свою работу, чтобы не изобретать велосипед и не напарываться на издревле известные грабли.
Даже если у вас нет ТЗ с тезаурусом и перечнем иллюстраций — структурированное и понятное хранение имеющейся документации облегчит жизнь всей команды. А также сподвигнет вас и коллег более собранно и ответственно относиться к проекту.
Источник