Внесение изменений в техническую документацию: Внесение изменений в техническую документацию, корректировка документов

Содержание

Внесение изменений в техническую документацию, корректировка документов

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

Обстоятельства, при которых производят данный процесс

Корректировка технической документации необходима:

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

Выполнение корректировки технических документов

Изменение технической документации производится на основании извещения об изменении.

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

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

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

Допускается производить процедуру с помощью нескольких приемов:

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

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

Ст. 744 ГК РФ. Внесение изменений в техническую документацию

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

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

3. Подрядчик вправе требовать в соответствии со статьей 450 настоящего Кодекса пересмотра сметы, если по не зависящим от него причинам стоимость работ превысила смету не менее чем на десять процентов.

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

См. все связанные документы >>>

1. Пункты 1 и 2 комментируемой статьи говорят о праве заказчика в одностороннем порядке изменить техническую документацию и тем самым в одностороннем порядке изменить условие о предмете договора, т.е. об объеме, содержании работ и т.п.

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

В п. 1 предполагается, что стороны при согласовании сметы предусмотрели в ней денежные средства, направленные на оплату непредвиденных расходов, не учтенных в технической документации. Поэтому заказчик, принимая решение об изменении технической документации, вправе рассчитывать на неизменность договорной цены. Однако решение заказчика о пересмотре технической документации без изменения стоимости строительства может существенно затронуть интересы подрядчика. Поэтому в целях сбалансирования интересов сторон ГК РФ предусмотрел два ограничения в праве заказчика в одностороннем порядке изменить техническую документацию без внесения изменений в смету. Во-первых, ограничение по стоимости дополнительных работ. Стоимость работ не должна превышать 10% указанной в смете общей стоимости строительства, т.е. быть относительно невелика по объему. Во-вторых, ограничение, касающееся существа изменения технической документации: не должен изменяться характер работ (изменение технической документации не должно привести к замене работ по капитальному ремонту на работы по строительству нового объекта). Если оба указанных условия заказчиком соблюдены, то подрядчик не вправе отказаться от дополнительных работ, вызванных изменением технической документации.

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

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

3. В п. 3 комментируемой статьи названо специальное основание для пересмотра сметы по требованию подрядчика — удорожание строительства, когда по независящим от подрядчика причинам стоимость работ превысила смету не менее чем на 10%.

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

Если по тем же самым обстоятельствам стоимость работ возросла менее чем на 10% (например, на 5%), то смета не пересматривается и ее превышение компенсируется за счет средств подрядчика.

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

4. Подрядчик как профессиональный исполнитель работ обладает специальными познаниями и опытом. В силу этого п. 4 комментируемой статьи закрепляет право подрядчика, установившего дефекты в технической документации, устранить их своими силами и средствами. Заказчик же обязан возместить подрядчику расходы, понесенные в связи с устранением подобных дефектов. Условием возмещения расходов является их разумность, предполагаемая исходя из п. 3 ст. 10 ГК РФ. Следовательно, заказчик может отказаться от возмещения расходов по устранению дефектов в технической документации, только доказав их неразумность.

5. Судебная практика:

— Постановление ФАС Северо-Кавказского округа от 24.05.2011 по делу N А32-25285/2010;

— Постановление ФАС Западно-Сибирского округа от 22.04.2009 N Ф04-1938/2009(3628-А81-38), Ф04-1938/2009(3630-А81-38) по делу N А81-1414/2008;

— Постановление ФАС Центрального округа от 23.01.2009 N Ф10-6102/08 по делу N А35-1431/08-С25.

NormaCS ~ Ответы экспертов ~ Какой порядок внесения изменений в рабочую и проектную документацию?

1. Как указано в 744 статье Гражданского кодекса Российской Федерации:

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

2. Внесение в техническую документацию изменений в большем против указанного в пункте 1 настоящей статьи объёме осуществляется на основе согласованной сторонами дополнительной сметы».

Согласно пункту 1.3.6.3. Методических указаний по применению справочников базовых цен на проектные работы в строительстве, утв. приказом Минрегиона России от 29.12.2009 № 620, зарегистрированным в Минюсте России 23.03.2010 (регистрационный № 16686), ценами указанных справочников не учтены затраты на «Внесение изменений в проектную и рабочую документацию (за исключением исправления ошибок, допущенных проектной организацией)»

.

Из приведённых выше извлечений из законодательного и нормативно-технического актов следует, что заказчик вправе давать поручения проектировщику, связанные с внесением изменений в техническую (рабочую) документацию:

− безвозмездно – в случае исправления ошибок, допущенных проектной организацией;

− на договорной основе – в случае подготовки новых технических решений, необходимость которых выявилась в процессе строительства.

2. Что касается проектной документации, то в отношении неё следует иметь в виду следующее.

2.1 Пункт 2 статьи 8 Федерального закона от 21.07.97 № 116-ФЗ «О промышленной безопасности опасных производственных объектов» устанавливает:

«Отклонения от проектной документации опасного производственного объекта в процессе его строительства, реконструкции, капитального ремонта, а также от документации на техническое перевооружение, капитальный ремонт, консервацию и ликвидацию опасного производственного объекта в процессе его технического перевооружения, консервации и ликвидации

не допускаются. Изменения, вносимые в проектную документацию на строительство, реконструкцию опасного производственного объекта, подлежат экспертизе проектной документации в соответствии с законодательством Российской Федерации о градостроительной деятельности».

2.22.2 В соответствии с пунктом 44 Положения об организации и проведении государственной экспертизы проектной документации и результатов инженерных изысканий, утв. постановлением Правительства Российской Федерации от 05.03.2007 № 145:

«Проектная документация и (или) результаты инженерных изысканий направляются повторно (2 и более раза) на государственную экспертизу после устранения недостатков, указанных в отрицательном заключении государственной экспертизы, или при внесении изменений в проектную документацию, получившую положительное заключение государственной экспертизы, в части изменения технических решений, которые влияют на конструктивную надёжность и безопасность объекта капитального строительства.

Проектная документация, получившая положительное заключение государственной экспертизы, по инициативе застройщика или технического заказчика может быть направлена повторно (2 и более раза) на государственную экспертизу в случае внесения в неё изменений в части технических решений, которые не влияют на конструктивную надёжность и безопасность объекта капитального строительства.

Повторная государственная экспертиза осуществляется в порядке, предусмотренном настоящим Положением для проведения первичной государственной экспертизы.

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

2.3 Частью 7 статьи 52 Градостроительного кодекса Российской Федерации от 29.12.2004 № установлено:

«7. Отклонение параметров объекта капитального строительства от проектной документации, необходимость которого выявилась в процессе строительства, реконструкции, капитального ремонта такого объекта, допускается только на основании вновь утвержденной застройщиком, техническим заказчиком, лицом, ответственным за эксплуатацию здания, сооружения, или региональным оператором проектной документации после внесения в нее соответствующих изменений в порядке, установленном уполномоченным Правительством Российской Федерации федеральным органом исполнительной власти».

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

3 Ведение исполнительной документации обеспечивается лицом, осуществляющим строительство, который осуществляет сбор всех необходимых документов и материалов, входящих в её состав. Это положение установлено частью 6 статьи 52 Градостроительного кодекса Российской Федерации от 29.12.2004 № 190-ФЗ и подтверждается РД-11-02-2006 «Требования к составу и порядку ведения исполнительной документации при строительстве, реконструкции, капитальном ремонте объектов капитального строительства и требования, предъявляемые к актам освидетельствования работ, конструкций, участков сетей инженерно-технического обеспечения», утв. приказом Ростехнадзора от 26.12.2006 № 1128).

При этом, как указано в пункте 5.6 РД-11-02-2006, в составе исполнительной документации должен присутствовать:

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

Внесение изменений в проектную документацию прошедшую экспертизу

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

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

Когда вносятся экспертизы в проект

Изменения проектной документации не являются исключением из правил. Градостроительный кодекс нашей страны требует изменения документации в случае, если в процессе выполнения работ по возведению объекта были выявлены ее недостатки либо несоответствие указанных данных фактическим. Это требование отражено в ст. 52.

Тот же градостроительный кодекс указывает, что после внесения корректив в проект они должны быть проверены в процессе проведения экспертизы. Исключения из этого правила допускаются в двух случаях:

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

Внесение изменений в проект после прохождения первоначальной экспертизы требует повторной проверки и согласно Постановлению Правительства №145, принятому в 2008 году. Этот документ требует назначения экспертного исследования в случае, если ранее проверенный проект был изменен и правки коснулись технических решений, влияющих на надежность и безопасность.

Когда необходима экспертиза изменений

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

Экспертиза после изменения проекта необходима в следующих случаях:

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

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

Перечень изменений, связанных с безопасностью

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

Перечень работ, которые влияют на безопасность, четко закреплено приказом К624, принятым 30 декабря 2009 года. В этом документе приведен исчерпывающий список, который можно условно разделить на три группы:

  • Инженерные изыскания;
  • Подготовка проектных документов;
  • Строительство новых, реконструкция и ремонт старых объектов.

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

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

Порядок проведения исследования

Внесение изменений в проект, как и последующая проверка этих изменений экспертом, может проводиться любое количество раз. Независимо от количества проверок порядок их проведения не меняется.

В отличие от полного первичного исследования после внесения изменений экспертами оценивается:

  • Та часть проекта, которая подвергалась правке;
  • Совместимость внесенных изменений с остальными частями проекта, которые анализировались специалистом ранее.

Как заказать экспертизу

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

Для начала исследования необходимо предоставить в адрес экспертной организации:

  1. Заявление о проведении исследования.
  2. Предыдущую версию проектной документации.
  3. Копию предыдущего заключения эксперта.
  4. Задание на изменение проекта.
  5. Документ, в котором указан весь перечень изменений в документации.

Про внесение изменений в проектную документацию

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

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

  • СТБ 2255—2012 (Система проектной документации для строительства. Основные требования к документации строительного проекта) (РБ).
  • ГОСТ 21.1101—2013 (Система проектной документации для строительства. Основные требования к проектной и рабочей документации) (РФ).
  • ГОСТ 2.503-90 (Правила внесения изменений) (РФ).

Но, сегодня тема не о правилах оформления изменений, а о том, когда это следует делать.

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

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

Согласитесь, нет смысла перед экспертизой печатать 5 экземпляров и передавать заказчику.

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

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

Давайте откроем СТБ 2255—2012 и обратим внимание, как называется раздел с правилами внесения изменений.

7 Правила внесения изменений в документацию строительного проекта, выданную заказчику.

Получается, изменения вносятся в документацию, выданную заказчику. Какой смысл передавать заказчику ПСД с изменениями? Одно дело, когда лист идет с заменой и совсем другое, когда весь лист в изменениях. Зачем заказчику видеть эти изменения, если он эту документацию видит впервые?

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

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

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

Советую почитать:

Вы можете пролистать до конца и оставить комментарий. Уведомления сейчас отключены.

Внесение изменений в документацию в ходе работ по договору


УСЛУГИ СТРОИТЕЛЯМ  ›      ОБРАЗЦЫ и ШАБЛОНЫ  ›      ПОШАГОВЫЕ ИНСТРУКЦИИ  ›      ПОЛЕЗНЫЕ СОВЕТЫ  ›      СТРОЙПОДРЯД: ОБЩЕЕ ИНФО  ›
НАШ НОВЫЙ ПРОЕКТ НОВЫЙ САЙТ с ШАБЛОНАМИ ПИСЕМ   БОЛЬШЕ ИНФОРМАЦИИ  

ВОЗМОЖНОСТИ

   

Много шаблонов и образцов

Инструкции и правила

ПОДРОБНЫЕ действия Подрядчиков
в различных ситуациях

ПРЕИМУЩЕСТВА

   

Ничего лишнего

Грамотные формулировки

Полный охват всех стадий
деятельности Подрядчика


Уникальный интернет-ресурс, предназначенный только для упрощения и ускорения подготовки писем и работы с Заказчиком
УДОБНО  БЫСТРО  ГРАМОТНО  Подрядчики всегда знают, что им делать и оформлять   ПЕРЕЙТИ на САЙТ  

 

Внесение изменений в техническую документацию по договору строительного подряда регламентируется статьей 744 ГК РФ.

Статья 744. Внесение изменений в техническую документацию

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

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

3. Подрядчик вправе требовать в соответствии со статьей 450 настоящего Кодекса пересмотра сметы, если по не зависящим от него причинам стоимость работ превысила смету не менее чем на десять процентов.

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

Где применяется данная статья, что регулирует

Отношения сторон

•          Выполнение дополнительных работ.

•          Устранение неточностей и ошибок  в технической документации.

•          Замена материалов в ходе работ.

Основные выводы

•          Заказчик может менять техническую документацию, если изменения не превышают 10 %  от первоначальной стоимости строительных работ, а также не меняют характер работ.

•          Если изменения свыше 10 %, то данные изменения оформляются дополнительной сметой.

•          Подрядчик имеет право на перерасчет сметы, если стоимость работ (по независящих от него причинам) превысила 10% от первоначальной стоимости.

•          Подрядчик имеет право на  возмещение расходов, которые были вызваны изменением технической документации (например устранение дефектов в ТЗ).

•          Серьезные изменения в смете оформляются и оплачиваются как допработы (см. инфо по ст. 743).

•          Замена материалов оформляется согласовательными письмами.

•          Устные просьбы Заказчика «что-либо сделать еще…»  должны быть зафиксированы в письменном виде.


Что должно быть в контракте в соответствии с этой статьей

Желательно.

•          Регламент согласования,  выполнения и оплаты дополнительных работ.

•          Регламент замены материалов без превышения стоимости работ.

•          Условие о согласовании изменений в смете в конкретные сроки после уведомления, полученного от Подрядчика.

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

Данные условия, кроме юридической составляющей, имеют психологическую: Заказчик, увидев такие условия в контракте, с меньшей долей вероятности будет отказываться или от приемки работ или от подписания актов. Своего рода «ликбез».

Негативные последствия игнорирования положений и правил, установленных данной статьей

•          Если допработы не согласованы, Заказчик их не оплатит.

•          Если замена материалов не согласована, то Заказчик может потребовать демонтировать и применить «старый» материал.

•          Если «новая»  смета не согласована, то работы могут не принять, мотивируя тем, что они выполнены с отступлениям от ТЗ («старой» сметы).

Выводы

•          Заказчик может менять техническую документацию, если изменения не превышают 10 %  от первоначальной стоимости строительных работ, а также не меняют характер работ.

•          Подрядчик имеет право на перерасчет сметы, если стоимость работ (по независящих от него причинам) превысила 10% от первоначальной стоимости.

•          Если изменения свыше 10 %, то данные изменения оформляются дополнительной сметой.

•          Серьезные изменения в смете оформляются и оплачиваются как допработы (см. инфо по ст. 743).

•          Замена материалов оформляется согласовательными письмами.

•          Все устные просьбы Заказчика должны быть зафиксированы в письменном виде.

•          Необходимо включать в контракт условия по ст. 744 ГК РФ.




Если Вам необходима помощь в решении задач по строительному подряду
МЫ ГОТОВЫ

Грамотно и быстро подготовить письма, разъяснения и т.п.

Подготовить ответы на претензии, разъяснения по действиям

Проконсультировать, грамотно ответить на вопросы

РАБОТАЕМ
СО ВСЕМИ
РЕГИОНАМИ

НАЧАТЬ РАБОТАТЬ   ›

РЕЗУЛЬТАТЫ РАБОТЫ   ›

НАШИ УСЛУГИ   ›


РЕЗУЛЬТАТ. Решение задачи максимально быстро и с минимумом затрат

   ЮРИДИЧЕСКИЙ ОТДЕЛ      ДИСТАНЦИОННО 
ГРАМОТНАЯ РАБОТА КОМАНДЫ ОПЫТНЫХ ЮРИСТОВ

РОСТ ДОХОДОВ

Новые заказы

РЕГУЛЯРНО

Снизить затраты

на деятельность компании

Оптимизировать работу

с минимальными затратами

  ПОДРОБНЕЕ  


ТЕНДЕРНЫЙ КОНВЕЙЕР

Получать по 3 контракта

ЕЖЕМЕСЯЧНО

Делать заявки

безошибочно и без отклонений

Выигрывать тендеры

с МИНИМАЛЬНЫМ снижением

  ПОДРОБНЕЕ  


ТРОЙНАЯ ВЫГОДА

Набор УНИКАЛЬНЫХ

преимуществ

Обеспечить себя

контрактами на год

Уникальные алгоритмы

работы с тендерами

  ПОЛУЧИТЬ  


РУКОВОДСТВО СТРОЙПОДРЯД

Скачать руководство

БЕСПЛАТНО

Все под рукой,

от инструкций до шаблонов

Работать с Заказчиком

выгодно и грамотно

  СКАЧАТЬ  

Более 70 % наших клиентов обращаются к нам повторно либо рекомендуют нас своим коллегам!

 ЦЕНЫ на НАШИ УСЛУГИ 

Д

ДЕСЯТЬ лет Успешной и
безупречной работы

Т

ТРИСТА ПЯТЬДЕСЯТ Клиентов сотрудничают
на постоянной основе

В

ВОСЕМЬ ТЫСЯЧ Различных писем 
подготовлено нами

П

ПЯТЬДЕСЯТ МИЛЛИАРДОВ Суммарная стоимость
договоров подряда

Статья 744 ГК РФ с комментариями

Полный текст ст. 744 ГК РФ с комментариями. Новая действующая редакция с дополнениями на 2021 год. Консультации юристов по статье 744 ГК РФ.

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

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

3. Подрядчик вправе требовать в соответствии со статьей 450 настоящего Кодекса пересмотра сметы, если по не зависящим от него причинам стоимость работ превысила смету не менее чем на десять процентов.

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

Комментарий к статье 744 ГК РФ

1. Пункты 1 и 2 комментируемой статьи говорят о праве заказчика в одностороннем порядке изменить техническую документацию и тем самым в одностороннем порядке изменить условие о предмете договора, т.е. об объеме, содержании работ и т.п.

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

В п.1 предполагается, что стороны при согласовании сметы предусмотрели в ней денежные средства, направленные на оплату непредвиденных расходов, не учтенных в технической документации. Поэтому заказчик, принимая решение об изменении технической документации, вправе рассчитывать на неизменность договорной цены. Однако решение заказчика о пересмотре технической документации без изменения стоимости строительства может существенно затронуть интересы подрядчика. Поэтому в целях сбалансирования интересов сторон ГК РФ предусмотрел два ограничения в праве заказчика в одностороннем порядке изменить техническую документацию без внесения изменений в смету. Во-первых, ограничение по стоимости дополнительных работ. Стоимость работ должна не превышать 10% указанной в смете общей стоимости строительства, т.е. быть относительно невелика по объему. Во-вторых, ограничение, касающееся существа изменения технической документации: не должен изменяться характер работ (изменение технической документации не должно привести к замене работ по капитальному ремонту на работы по строительству нового объекта). Если оба указанных условия заказчиком соблюдены, то подрядчик не вправе отказаться от дополнительных работ, вызванных изменением технической документации.

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

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

3. В п.3 комментируемой статьи названо специальное основание для пересмотра сметы по требованию подрядчика — удорожание строительства, когда по не зависящим от подрядчика причинам стоимость работ превысила смету не менее чем на 10%.

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

Если по тем же самым обстоятельствам стоимость работ возросла менее чем на 10% (например, на 5%), то смета не пересматривается и ее превышение компенсируется за счет средств подрядчика.

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

4. Подрядчик как профессиональный исполнитель работ обладает специальными познаниями и опытом. В силу этого п.4 комментируемой статьи закрепляет право подрядчика, установившего дефекты в технической документации, устранить их своими силами и средствами. Заказчик же обязан возместить подрядчику расходы, понесенные в связи с устранением подобных дефектов. Условием возмещения расходов является их разумность, предполагаемая исходя из п.3 ст. 10 ГК РФ. Следовательно, заказчик может отказаться от возмещения расходов по устранению дефектов в технической документации, только доказав их неразумность.

5. Судебная практика:
— постановление ФАС Северо-Кавказского округа от 24.05.2011 по делу N А32-25285/2010;
— постановление ФАС Западно-Сибирского округа от 22.04.2009 N Ф04-1938/2009(3628-А81-38), Ф04-1938/2009(3630-А81-38) по делу N А81-1414/2008;
— постановление ФАС Центрального округа от 23.01.2009 N Ф10-6102/08 по делу N А35-1431/08-С25.

Консультации и комментарии юристов по ст 744 ГК РФ

Если у вас остались вопросы по статье 744 ГК РФ и вы хотите быть уверены в актуальности представленной информации, вы можете проконсультироваться у юристов нашего сайта.

Задать вопрос можно по телефону или на сайте. Первичные консультации проводятся бесплатно с 9:00 до 21:00 ежедневно по Московскому времени. Вопросы, полученные с 21:00 до 9:00, будут обработаны на следующий день.

Техническая документация по разработке программного обеспечения: типы и инструменты

Время чтения: 22 минуты

Техническая документация в программной инженерии — это общий термин, охватывающий все письменные документы и материалы, касающиеся разработки программных продуктов. Все продукты разработки программного обеспечения, созданные небольшой командой или крупной корпорацией, требуют некоторой сопутствующей документации. На протяжении всего жизненного цикла разработки программного обеспечения (SDLC) создаются различные типы документов.Документация существует для объяснения функциональности продукта, унификации информации, связанной с проектом, и позволяет обсуждать все важные вопросы, возникающие между заинтересованными сторонами и разработчиками.

Проектная документация по этапам и назначению

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

Гибкий и водопадный подход

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

Водопад — это линейный метод с отдельными целями для каждой фазы разработки. Команды, использующие водопад, тратят разумное количество времени на планирование продукта на ранних этапах проекта.Они создают обширный обзор основных целей и задач и планируют, как будет выглядеть рабочий процесс. Команды Waterfall стремятся создать подробную документацию до того, как начнется любой из этапов проектирования. Тщательное планирование хорошо работает для проектов с небольшими изменениями или без них, поскольку оно позволяет точно составлять бюджет и оценивать время. Однако планирование водопада оказалось неэффективным для долгосрочного развития, поскольку оно не учитывает возможные изменения и непредвиденные обстоятельства на ходу.По данным глобального исследования Agile, проведенного KPMG, 81% компаний инициировали Agile-трансформацию за последние три года.

Схема цикла Agile-разработки

Гибкий подход основан на командной работе, тесном сотрудничестве с клиентами и заинтересованными сторонами, гибкости и способности быстро реагировать на изменения. Основные строительные блоки гибкой разработки — это итерации; каждый из них включает в себя планирование, анализ, проектирование, разработку и тестирование. Вначале гибкий метод не требует исчерпывающей документации.Менеджерам не нужно много планировать заранее, потому что все может меняться по мере развития проекта. Это позволяет планировать точно в срок. Как следует из одной из ценностей Agile Manifesto, поставив «работающее программное обеспечение над исчерпывающей документацией», идея состоит в том, чтобы создавать документацию с информацией, которая необходима для продвижения вперед, когда это имеет наибольший смысл.

Сегодня Agile является наиболее распространенной практикой в ​​разработке программного обеспечения, поэтому мы сосредоточимся на практике документации, связанной с этим методом.

Виды документации

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

Соответствует следующей классификации.

Документация по программному обеспечению, наиболее часто используемая в Agile проектах

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

  • Документация по продукту
  • Технологическая документация

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

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

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

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

Продукт: Системная документация

Документация по системе

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

Документ о требованиях к продукции

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

Лучше всего написать документ с требованиями с использованием единого согласованного шаблона, которого придерживаются все члены команды. Форма в виде одной веб-страницы поможет вам сделать документ кратким и сэкономить время, затрачиваемое на доступ к информации.Вот пример одностраничного документа с требованиями к продукту, чтобы понять различные элементы, которые должны быть включены в ваш PRD. Тем не менее, вы должны помнить, что это не единственный способ составить этот документ.

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

Вот основные рекомендации, которые следует включить в документ с требованиями к продукту:

  1. Роли и обязанности .Начните свой документ с информации об участниках проекта, включая владельца продукта, членов команды и заинтересованных лиц. Эти детали прояснят обязанности и сообщат цели целевого выпуска для каждого из членов команды.
  2. Цели команды и бизнес-задача . Кратко опишите самые важные цели.
  3. Предпосылки и стратегическое соответствие . Кратко объясните стратегическую цель ваших действий. Зачем вы создаете продукт? Как ваши действия влияют на разработку продукта и соответствуют целям компании?
  4. Предположения. Создайте список технических или бизнес-предположений, которые могла бы иметь группа.
  5. Пользовательские истории. Перечислить или связать пользовательские истории, необходимые для проекта. Пользовательская история — это документ, написанный с точки зрения человека, использующего ваш программный продукт. Пользовательская история — это краткое описание действий клиентов и результатов, которых они хотят достичь.
  6. Критерии приемки. Это условия, которые указывают на завершение пользовательской истории. Основная цель критериев приемлемости — определить удовлетворительный результат для сценария использования с точки зрения конечного пользователя.Ознакомьтесь с нашими специальными статьями о критериях приемлемости и пользовательском приемочном тестировании, чтобы узнать больше.
  7. Взаимодействие с пользователем и дизайн . Свяжите со страницей исследования дизайна и каркасы.
  8. Вопросы. По мере того, как команда решает проблемы по ходу проекта, у них неизбежно возникает много вопросов. Хорошая практика — записывать все эти вопросы и отслеживать их.
  9. Не работает. Составьте список того, чем вы сейчас не занимаетесь, но планируете сделать в ближайшее время.Такой список поможет вам организовать работу в команде и расставить приоритеты.

Сделайте всю эту информацию более полной, используя следующие методы:

  • Используйте ссылки и якоря . Они помогут вам упростить чтение и поиск документа, поскольку читатели смогут постепенно понимать информацию. Например, вы можете предоставить ссылки на интервью с клиентами и ссылки на предыдущие обсуждения или другую внешнюю информацию, связанную с проектом.
  • Используйте графику и инструменты построения диаграмм , чтобы лучше сообщить о проблемах вашей команде. Люди более склонны воспринимать информацию, глядя на изображения, чем читая обширный документ. Различные визуальные модели помогут вам выполнить эту задачу и более эффективно обозначить требования. Вы можете включать диаграммы в свой процесс требований, используя следующие программные инструменты построения диаграмм: Visio, Gliffy, Balsamiq, Axure или SmartArt в Microsoft Office.

Пользовательский интерфейс Проектная документация

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

Документацию UX можно разделить на этапы. Этап исследования включает:

  • Персоны пользователей
  • Пользовательский сценарий
  • Карта сценария
  • Карта истории пользователя
  • Руководство по стилю UX

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

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

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

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

Пример карты пользовательской истории с разбивкой на выпуски

Источник: feedotter.com

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

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

  • Карты сайта
  • Каркасы
  • Мокапы
  • Прототипы
  • Схемы потоков пользователя или путь пользователя
  • Отчеты тестирования юзабилити

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

Пример структуры карты сайта

Источник: uxforthemasses.com

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

Схема работы пользователей приложения поиска работы

Источник: medium.com

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

Пример каркаса для мобильного приложения Peekaboo

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

Прототип — это макет, с которым вы можете взаимодействовать: нажимать несколько кнопок, перемещаться между разными страницами и так далее. Прототип можно создать с помощью инструмента для создания прототипов, такого как Sketch или MockFlow.Используя шаблоны, дизайнеры UX могут создавать интерактивные макеты на ранних этапах разработки, которые будут использоваться для тестирования удобства использования.

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

Проектный документ архитектуры программного обеспечения

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

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

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

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

Описание User Story. Свяжите истории пользователей со связанными бизнес-процессами и связанными сценариями. Вам следует избегать технических подробностей в этом разделе.

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

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

Схема архитектуры веб-приложения Azure

Источник: docs.microsoft.com

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

Исходный код, документ

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

Документы с исходным кодом могут включать, но не ограничиваются, следующие сведения:

  • Фреймворк для генерации HTML и другие применяемые фреймворки
  • Тип привязки данных
  • Шаблон дизайна с примерами (e.грамм. модель-представление-контроллер)
  • Меры безопасности
  • Прочие модели и принципы

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

Документация по обеспечению качества

В Agile есть разные типы приемочного тестирования пользователей. Мы выделили самые распространенные:

  • План управления качеством
  • Стратегия тестирования
  • План испытаний
  • Технические характеристики тестового корпуса
  • Контрольные листы испытаний

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

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

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

  • Список функций для тестирования
  • Методы испытаний
  • Таймфреймы
  • Роли и обязанности (например, модульные тесты могут выполняться командой QA или инженерами)

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

Контрольный список тестов — это список тестов, которые следует запускать в определенное время. Он показывает, какие тесты завершены, а сколько не удалось. Все пункты в контрольных листах теста должны быть определены правильно. Попробуйте сгруппировать контрольные точки в контрольных списках.Такой подход поможет вам отслеживать их во время работы и не потерять их. Если это помогает тестировщикам правильно проверить приложение, вы можете добавить комментарии к своим точкам в списке.

Техническое обслуживание и справочное руководство

В этом документе должны быть описаны известные проблемы с системой и способы их решения. Он также должен представлять зависимости между различными частями системы.

Документация по API

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

Документация по API

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

Продукт: Пользовательская документация

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

  • конечных пользователей
  • системные администраторы

Документация для конечного пользователя

Документация, созданная для конечных пользователей, должна максимально просто объяснить, как программное обеспечение может помочь в решении их проблем. Такие инструкции для пользователя могут быть предоставлены в печатном виде, онлайн или офлайн на устройстве. Вот основные типы пользовательских документов:

Краткое руководство содержит обзор функций продукта и дает основные рекомендации по его использованию.

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

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

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

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

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

  • Часто задаваемые вопросы
  • Видеоуроки
  • Встроенная поддержка
  • Порталы поддержки

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

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

Документация системного администратора

Документы системных администраторов не должны содержать информацию о том, как работать с программным обеспечением. Обычно административная документация охватывает установку и обновления, которые помогают системному администратору в обслуживании продукта. Вот стандартные документы системного администратора:

  • Функциональное описание — описывает функциональные возможности продукта.Большая часть этого документа создается после консультации с пользователем или владельцем.
  • Руководство системного администратора — объясняет различные типы поведения системы в разных средах и с другими системами. Он также должен содержать инструкции по устранению неисправностей.

Технологическая документация

Документация по процессу

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

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

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

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

Стандарты. Раздел о стандартах должен включать все стандарты кодирования и UX, которых команда придерживается на протяжении всего проекта.

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

Основная цель документирования процесса — уменьшить объем системной документации. Для этого напишите минимальный план документации. Составьте список основных контактов, дат выпуска и ваших ожиданий с предположениями.

Дорожные карты Agile-продуктов

Дорожные карты продукта

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

Есть три типа дорожных карт продукта, которые используются производственными группами Agile:

  • Стратегическая дорожная карта
  • Дорожная карта технологий или ИТ
  • План выпуска

Стратегическая дорожная карта — это стратегический документ высокого уровня, который содержит общую информацию о проекте. В стратегических дорожных картах обычно указываются видение и долгосрочные цели.В случае гибкой разработки продукта дорожная карта может быть разбита на темы. Темы — это несколько задач, которые должна выполнить команда и которые каким-то образом связаны. Например, тема может звучать как «повысить скорость загрузки страницы», что влечет за собой несколько действий.

Группировка информации по темам делает дорожную карту очень гибкой и обновляемой, что отлично подходит для разработки на основе спринтов. Лучший совет относительно стратегической дорожной карты — включать только важную информацию.В противном случае вы рискуете превратить свою дорожную карту в неуклюжую схему, которую сложно понять и поддерживать.

Пример дорожной карты стратегического программного обеспечения

Источник: productplan.com

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

Пример технологической дорожной карты

Источник: hutwork.com

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

Пример плана выпуска

Источник: productplan.com

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

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

Инструмент общего назначения

Существует бесчисленное множество инструментов для совместной работы для команд разработчиков программного обеспечения. Они могут помочь сформулировать требования, поделиться информацией и документировать функции и процессы:

  • Atlassian Confluence — самый популярный инструмент для совместных проектов, в котором есть вся экосистема для управления требованиями к продукту и написания документации.Confluence известен стабильной вики-системой и эффективным интерфейсом управления пользовательскими историями.
  • Document 360 — это база знаний самообслуживания / платформа документации по программному обеспечению, разработанная для продуктов «Программное обеспечение как услуга».
  • bit.ai — это инструмент для совместного создания, хранения документации, обмена данными и использования вики-системы. Документация интерактивна, что означает, что разработчики могут встраивать блоки или фрагменты кода прямо в документ и делиться им одним щелчком мыши. Закончив редактирование документации, вы можете сохранить ее в формате PDF или в формате markdown и опубликовать на любой другой платформе.
  • Github не нуждается в представлении, за исключением тех, кто хочет использовать его для документации по программному обеспечению. Он предоставляет вам собственную вики-систему и позволяет преобразовывать вашу документацию в привлекательные витрины веб-сайтов.

Редакторы Markdown

Поскольку документацию по программному обеспечению легче использовать в Интернете, ее необходимо создавать в надлежащем формате. Вот почему используются текстовые языки разметки. Самый популярный из них — это разметка, которая легко конвертируется в HTML и не требует специальных знаний для ее использования.Разметка используется на GitHub и Reddit и практически везде для веб-документации. Итак, вот несколько редакторов Markdown, которые могут быть полезны для создания документов для вашего проекта:

Специальные инструменты для дорожной карты

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

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

Инструменты для документации UX

Самыми популярными инструментами для проектирования пользовательского интерфейса являются инструменты для создания прототипов, которые помогают создавать эскизы, макеты, каркасы и интерактивные прототипы:

  • Sketch — это простой, но мощный инструмент векторного дизайна с веб-приложением и настольным клиентом Mac. Sketch хорошо известен и довольно прост, предлагая достаточно возможностей для проектирования интерфейсов.

Интерфейс эскиза

  • InVision — один из самых популярных инструментов для создания прототипов. InVision славится своими функциями совместной работы и кроссплатформенными возможностями, что делает его отличным инструментом для разработки будущих интерфейсов.
  • UXPin — это инструмент для проектирования Mac и Windows, который позволяет создавать любые типы чертежей. Вы также можете загрузить свои эскизы или каркасы из других продуктов и сделать из них интерактивный прототип.
  • Adobe XD — где XD означает опыт дизайна.Продукт ориентирован на UX-специалистов. Это позволяет дизайнерам создавать прототипы с высокой точностью и делиться ими через приложение.

Инструменты для документации API

Чаще всего процесс создания документации API автоматизирован. Программисты или технические писатели могут писать документацию вручную или использовать генераторы документации API:

  • Swagger — это бесплатный сервис самодокументируемого программного обеспечения, предназначенный для создания и обновления веб-сервисов и API RESTful.
  • RAML 2 HTML — это простой генератор документации, использующий спецификации RAML.

Инструменты для технических писателей

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

  • MadCapFlare — мощное облачное программное обеспечение с функцией многоканальной публикации, многоязычной поддержкой, обширными учебными ресурсами и многим другим.
  • Adobe RoboHelp — полнофункциональная CMS, позволяющая создавать мультимедийный контент, удобное управление микроконтентом, совместную работу для контроля версий и т. Д.
  • ClickHelp — отмеченная наградами платформа, предлагающая простой переход с других программ, гибкие варианты разрешений и ряд возможностей отчетности.

Образцы и шаблоны программной документации

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

Шаблоны общей проектной документации

Следующие источники предоставляют широкий спектр шаблонов, связанных с разработкой программного обеспечения и управлением проектами:

  • Atlassian Confluence Templates предлагает готовые шаблоны проектной документации общего назначения вместе со своим продуктом.
  • ReadySET Pro — это большая библиотека шаблонов документации по программному обеспечению в HTML, которая включает документы планирования, архитектуру, дизайн, требования, тестирование и многое другое.
  • ReadTheDocs — это универсальный шаблон, созданный на платформе ReadTheDocs, содержащий инструкции по написанию каждого типа документа, который может вам понадобиться, от архитектуры и диаграмм UML до руководств пользователя.

Шаблоны дорожных карт продуктов

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

Шаблоны документации по обеспечению качества

Если вы все еще ищете шаблоны, связанные с контролем качества, вы можете проверить здесь:

  • StrongQA.com имеет различные шаблоны документации для QA-специалистов. К ним относятся контрольные списки тестирования, шаблоны дымового тестирования, планы тестирования и многое другое.
  • Template.net имеет раздел с шаблонами планов обеспечения качества.
  • EasyQA предлагает SDK для тестирования программного обеспечения и предоставляет шаблоны с подробным руководством по созданию качественного плана тестирования.
  • Тестирование программного обеспечения — это большая платформа, включающая блог, форум и всевозможные информационные материалы для специалистов по тестированию.

Шаблоны документов для разработки программного обеспечения

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

Примеры специализированных архитектур: AWS, Microsoft Azure и Google Cloud

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

  • Amazon — Центр архитектуры AWS предоставляет рекомендации по архитектуре AWS, инфраструктуры, инструменты и передовые методы выполнения архитектурных рабочих нагрузок в облаке.
  • Microsoft — этот ресурс предлагает множество полезных материалов по архитектуре Azure, включая примеры сценариев, схемы архитектуры и многое другое.
  • Google — посетите официальную библиотеку иконок с образцами для построения архитектурных схем Google Cloud.

Как писать документацию по программному обеспечению: общие советы

Есть несколько общих практик, которые можно применить ко всем основным типам документации, которые мы обсуждали выше.

Напишите достаточно документации

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

Учитывайте свою аудиторию

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

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

Использовать перекрестные ссылки

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

Не игнорируйте глоссарии

Документация может быть предназначена для внутреннего или внешнего использования. В случае внешних документов лучше дать четкое объяснение каждого термина и , его конкретное значение в проекте. Документация должна сообщать идеи на понятном языке, чтобы установить lingua franca между заинтересованными сторонами, внутренними членами и пользователями.

Поддерживайте актуальность документации по программному обеспечению

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

Рекомендуется установить какой-либо график обслуживания и обновления. Вы можете делать это через определенные промежутки времени, то есть еженедельно или ежемесячно, или связать это со своим планом разработки и, скажем, обновлять документы после каждого выпуска.Автоматические электронные письма или примечания к выпуску могут помочь вам следить за изменениями, внесенными командой разработчиков.

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

Документация — совместная работа всех членов команды

Гибкий метод основан на совместном подходе к созданию документации. Если вы хотите добиться эффективности, поговорите с программистами и тестировщиками о функциях программного обеспечения.Затем, после того как вы написали некоторую документацию, поделитесь ею со своей командой и получите обратную связь. Вы также можете посещать собрания команды, чтобы быть в курсе, или регулярно проверять доску Канбан. Чтобы получить больше информации, попробуйте комментировать, задавать вопросы и побуждать других делиться своими мыслями и идеями. Каждый член команды может внести ценный вклад в создаваемые вами документы.

Нанять технического писателя

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

Дополнительные советы по созданию и поддержке документации

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

  • считают наиболее эффективным средством передачи информации.Например, создание аудио- или видеозаписей может быть отличным вариантом для сбора требований, руководств пользователя и т. Д .;
  • вставлять ссылки на соответствующие онлайн-статьи или информационные страницы вместо того, чтобы воспроизводить их в своей документации;
  • генерирует диаграммы из кода или баз данных, когда это возможно, а не создает их с нуля;
  • используйте скриншоты и другие изображения — они помогут вам быстро найти то, что нужно обновить, и вам не придется читать весь текст;
  • рассмотрите возможность хранения вашей технической документации вместе с исходным кодом, просто храните их отдельно.Это поможет поддерживать его в актуальном состоянии и позволит всем узнать, где его найти;
  • настроить доступ, чтобы избежать лишних изменений. Предоставьте разрешения на редактирование потенциальным авторам, в то время как те, у кого есть доступ только для просмотра, по-прежнему могут видеть информацию, но не изменять ее;
  • убедитесь, что авторы могут иметь быстрый и легкий доступ к документации для просмотра и обновления. Устранение таких препятствий, как ненужные процедуры авторизации и / или утверждения;
  • сохранять предыдущие версии и архивировать электронные письма по проекту, так как вам может потребоваться вернуться к ним в будущем;
  • не забудьте сделать резервную копию;
  • используйте теги для облегчения поиска;
  • , если документация — это способ поделиться знаниями, подумайте о других способах общения или выясните, почему члены команды просто не говорят об этом.Это может быть полезно для совместной работы и сокращает объем необходимой документации.

Заключительное слово

Гибкая методология побуждает инженерные команды всегда сосредоточиваться на предоставлении ценности своим клиентам. Этот ключевой принцип также необходимо учитывать в процессе создания документации по программному обеспечению. Должна быть предоставлена ​​хорошая документация по программному обеспечению, будь то спецификация программного обеспечения для программистов и тестировщиков или руководства по программному обеспечению для конечных пользователей. Полная документация по программному обеспечению является конкретной, краткой и актуальной.

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

Техническая документация. Как улучшить свою технику… | Омар Рабболини | The Startup

Из серии «Поваренная книга программной инженерии» — Как улучшить свою инженерную практику с помощью хорошей стратегии технической документации

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

Фото Фабиана Гросса на Unsplash

Младший инженер Unikorn Inc.

Меня зовут Матильда. Я присоединился к Unikorn Inc. чуть более трех месяцев назад, проработав около полутора лет в другом стартапе, где инженерная практика была не так хороша. Босс хотел, чтобы все было сделано быстро, без особой заботы о качестве, и тогда нам приходилось тушить пожары на производстве каждый раз, когда выпускался релиз.

Мне здесь нравится, мои товарищи по команде дружелюбны и знают свое дело, и мы создаем продукт, которым многие люди пользуются каждый день. Единственное, что мне не очень нравится, так это процесс. Я чувствую, что иногда приходится соблюдать слишком много правил, и это заставляет меня писать код медленнее. Я особенно не понимаю, почему нам нужно писать так много документов, чтобы объяснить, как все работает. Для меня проще и быстрее писать и читать код напрямую.

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

Фото Helloquence на Unsplash

Почему мы пишем техническую документацию

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

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

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

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

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

Фото Джубала Кеннета Бернала на Unsplash

Организация информации

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

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

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

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

Фото Флориана Клауэра на Unsplash

Технические характеристики

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

Цель документа с техническими спецификациями (или tech spec ) — объяснить, как реализована функция, выполняя разные роли на разных этапах процесса разработки:

  • До внедрения : Это позволяет людям проверить план, чтобы убедиться, что он имеет смысл, а также его соответствие функциональным спецификациям.
  • Во время реализации : Он обеспечивает контракт между различными частями разрабатываемой функции и единую точку отсчета для инженеров, участвующих в работе.
  • После внедрения : Он служит справочным материалом для будущего обслуживания и модификации функции.

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

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

Существуют различные способы смягчения этой проблемы, самый простой и наименее затратный по времени — оставить противоречие, как оно есть в различных задействованных документах, и вместо этого полагаться на управление версиями компонентов для определения текущей «истинности» системы в заданный момент времени. время.

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

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

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

В качестве примечания: принудительное управление версиями компонентов и явные ссылки в технических спецификациях также побуждают команду задуматься о влиянии каждого изменения и о том, как обеспечить обратную совместимость и соответствующую миграцию, если это необходимо, например, в общедоступных API или когда изменение схемы базы данных.

Фото Сергея Золкина на Unsplash

Архитектурные документы

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

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

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

  • Объем : Технические характеристики относятся к реализации конкретной функции, в то время как в документации по архитектуре система и ее компоненты рассматриваются как целые единицы
  • Право собственности : В то время как различные технические спецификации обычно принадлежат руководителю функции (то есть инженеру, который руководит реализацией соответствующей функции), документ архитектуры должен принадлежать техническому органу команды (либо архитектору программного обеспечения, либо архитектурному «комитету». ) для обеспечения соответствия внутренним и внешним правилам и нормам, которые более широко применяются к системе или даже ко всей компании
  • Постоянство : По мере изменения функций некоторые технические характеристики становятся менее актуальными и со временем используются реже.С другой стороны, программная архитектура всегда жива и развивается, и ее документацию необходимо поддерживать в актуальном состоянии. Таким образом, к документам по архитектуре программного обеспечения должны применяться разные правила (например, с точки зрения устаревания и регулярного пересмотра), и процесс должен их четко определять.
Фотография Кристофера Гауэра на Unsplash

Документация по коду

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

Аннотации — это мощный инструмент для автоматического создания документации, в которой подробно описывается работа кода (например, справочник по API). Обычно они принимают форму комментариев в соответствии с определенным стилем, определенным в системе аннотаций (например, JSDoc для кода Javascript). Большинство современных IDE (например, Visual Studio Code, Android Studio и т. Д.) Могут использовать эти системы аннотаций для создания встроенной справки на основе исходного кода, а также для обеспечения функции автозаполнения.

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

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

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

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

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

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

Фото Энни Спратт на Unsplash

Выбор правильного формата

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

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

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

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

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

Фото Helloquence на Unsplash

Измерение эффективности документации

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

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

  • Получите оценку исправления ошибок от эксперта по конкретному компоненту и посмотрите, сколько времени потребуется неспециалисту, чтобы исправить фактическую проблему
  • Посмотрите, сколько времени требуется новым членам команды, чтобы освоить систему, хотя это может быть непросто, поскольку система должна постоянно развиваться
  • Соберите обратную связь (например,грамм. в 1: 1с) от команды по качеству и охвату документации

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

Документация (Руководства)

Документация (Руководства)

Раздел 2.8.2

Документация (Руководства)

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

При продаже продукции требуется два вида документации: техническая документация и пользовательская. документация.

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

Руководства должны быть подготовлены с целью быстрого предоставления информации эксперт или обычный читатель. Помните об аудитории в первую очередь. В руководствах приоритетом является простота поиска и чтения информации. Следовательно, руководства должны содержать эти компоненты:

Простые в использовании элементы поиска, такие как оглавление, указатели и заголовки страниц.

Полезные схемы с большим изображением и крупным планом, упрощающие читатель познакомится с технологией

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

Дизайн страниц, в котором материал размещен эффективно, с эффективными маркировка, фрагменты и пробелы

Четкое ручное расположение разделов и глав организованы вокруг важных задач

Простой, экономичный стиль, в котором есть все, что нужно

Последовательная, хорошо продуманная терминология, позволяющая читателю сосредоточиться на задаче.

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


## Документация (Руководства) ##

[На главную | Оглавление | Хронология написания | Индекс | Помощь | Кредиты]

Техническая документация: изменения согласно MDR

Основным ключевым элементом процесса утверждения медицинского изделия является техническая документация.В новом MDR добавлены дополнительные требования. Поэтому более чем важно не сбиться с пути с таким количеством формальностей. Прочтите сообщение, чтобы узнать, как это сделать!

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

Обозначение и определение

В целом термин техническая документация (сокращенно TD) является общим термином для документации продукта, который свидетельствует о том, что медицинское устройство соответствует общим требованиям безопасности и производительности (MDR приложение I), то есть медицинское изделие соответствует нормативам.Независимо от класса медицинского изделия — всегда должна быть в наличии техническая документация. В частности, для TD должен соответствовать требованиям властей, чтобы получить соответствие CE для своего медицинского устройства. В дополнение к этому, продукты класса Is, Im, Ir должны также частично соответствовать требованиям нотифицированного органа, продукты класса IIa, IIb и III должны соответствовать полностью.

В приложениях II и III MDR точно показывает, что должна содержать каждая документация.Для сравнения: раньше MDD не особо оговаривал содержание, теперь MDR ужесточает условия и даже делает еще один шаг вперед, поскольку определяет критерии TD для послепродажного наблюдения.

Содержимое согласно MDR

MDR четко определяет, какие элементы должны быть в технической документации :

  1. Описание и спецификации устройства, включая варианты и аксессуары
    1.1 Описание устройства
    a) название
    b ) UDI
    c) группа пациентов и их медицинское состояние
    d) принцип действия
    e) обоснование того, что данный продукт является медицинским устройством
    f) классификация
    g) объяснение нововведений
    h) описание принадлежностей и, если применимо, компоненты системы
    i) конфигурация / варианты
    j) детали / компоненты
    k) сырье и элементы, контактирующие с телом человека
    l) технические характеристики
    1.2 Ссылка на предыдущие и аналогичные поколения устройства

  2. Информация, предоставляемая производителем: этикетка устройства и упаковки, а также инструкции по применению

  3. Информация о конструкции и производстве

  4. Общие требования безопасности и производительности (приложение I)

  5. Анализ выгод и рисков и управление рисками (приложение I, разделы 1, 3, 8)

  6. Верификация и валидация продукции
    6.1 Доклинические и клинические данные
    6.2 Дополнительная информация, необходимая в особых случаях:
    a) лекарственный препарат как неотъемлемая часть
    b) ткани или клетки человеческого или животного происхождения
    c) комбинации веществ для абсорбции, диспергирования, метаболизма, выделения
    d) обоснование использования CMR -Вещества или вещества, нарушающие работу эндокринной системы
    e) информация, относящаяся к стерилизации
    f) информация об измерении функции
    g) описание комбинации / конфигурации с подключенными устройствами

Для имплантируемых устройств и устройств класса III (за исключением устройств, изготовленных на заказ или исследовательских устройств) производитель должен составить краткий отчет о безопасности и клинических характеристиках (статья 32).

Техническая документация по послепродажному надзору (приложение III) фокусируется на следующем:

    1. План послепродажного надзора
    2. Отчет о послепродажном надзоре (класс I), периодический отчет по обновлению безопасности PSUR (класс IIa, IIb, III)

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

Важным фактом является то, что с новым MDR Комиссия ЕС может при необходимости изменять требования к TD в соответствии с техническим прогрессом. На практике это означает: техническая документация на каждое медицинское изделие должна постоянно обновляться.

Существует ли техническая документация на one ?

К сожалению, на этот вопрос приходится отвечать «нет». MDR действительно дает указания относительно того, какой контент должен присутствовать в технической документации для утверждения в европейской зоне, однако он не дает явной информации с точки зрения структуры и единообразия документов.Это относится только к «ясному, организованному, легко доступному для поиска и недвусмысленному способу» (приложение II к MDR). Это означает, что в конечном итоге каждая техническая документация имеет одинаковую форму содержания, но что касается общей структуры или структуры глав, между отдельными авторами вполне могут быть различия. Тем не менее, большинство авторов технической документации, а также органы власти или уполномоченные органы часто следуют спецификациям в признанных стандартах / руководящих принципах (современное состояние). Здесь следует отметить, что единообразная структура технической документации (своего рода модели), представленная MDR, безусловно, будет иметь свои преимущества как для властей, так и для производителей.

Определенным ориентиром с точки зрения структуры является так называемый STED (Краткая техническая документация), который был создан Рабочей группой по глобальной гармонизации (GHTF), предшественником сегодняшнего Международного форума регуляторов медицинского оборудования (IMDRF). . Его цель заключалась в разработке глобальных уникальных приложений для утверждения медицинских устройств. В настоящее время STED признан в США, Европе, Канаде, Австралии и Японии.

Но еще по одной причине не существует одной технической документации, для: разных стран, разных… документация. За пределами ЕС MDR не применяется, поэтому действуют другие правила.

В U.S. , в соответствии с правилами FDA , требуются другие типы документов в связи с технической документацией: основная запись устройства, файл истории проектирования и запись истории устройства. DMR содержит документы, в которых описывается, как производится, эксплуатируется и обслуживается медицинское устройство. Модель DHF иллюстрирует полную историю разработки продукта, а модель DHR служит доказательством того, что медицинское устройство произведено в соответствии со спецификациями DMR и что все основные критерии выполнены.Таким образом, документы также способствуют обеспечению качества. Только вместе DHF, DMR и DHR делают понятным каждый этап создания медицинского изделия, а также процесс его разработки и производства. Следовательно, основная запись устройства, файл истории проектирования и запись истории устройства являются важными компонентами для составления TD.

В Canada структура технической документации основана на структуре STED. Канадские власти также опубликовали для этой цели собственную модель.

Всегда применимо: производители должны быть точно проинформированы о нормативных требованиях, касающихся TD в стране, где они хотят получить разрешение на медицинское изделие.

Что еще нужно учитывать

Однако многие требования к технической документации MDR уже частично известны из стандартов, таких как DIN EN ISO 13485, DIN EN ISO 14971 или DIN EN 62366-1. Часто они уже применяются в соответствующих компаниях.Таким образом, в рамках MDR применение этих требований к TD находится в пределах возможности. Поскольку MDR действительно дает ответ на один вопрос: «лицо, ответственное за соблюдение нормативных требований» (статья 15) также отвечает за составление технической документации и поддержание ее в актуальном состоянии.

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

Обращаем ваше внимание на то, что все данные и списки не претендуют на полноту, не гарантируются и служат в чистом виде.

4 совета по обеспечению актуальности вашей технической документации

Согласно недавнему опросу Tech-Clarity, 30% руководителей сервисных служб заявили, что их техническая документация содержит неточности, многие из которых состоят из устаревшей информации о деталях.

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

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

1. Разработка цифровых руководств по обслуживанию

Field Technologies Online обнаружила, что 41% техников по обслуживанию на местах используют смартфоны в повседневной работе.Более трети используют ноутбуки, ноутбуки или гибридные устройства, а 22% используют планшеты.

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

2. Обратитесь к команде инженеров (правда, сделайте это)

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

Конечно, открытие этого канала — полдела. Вот несколько советов по подключению к инженерному делу:

  • Используйте высшее руководство: Попросите вице-президента поговорить с вице-президентом или директором по разработке продуктов (или инженерам, в зависимости от настроек вашей организации).
  • Пообщаться с инженером: Назначьте встречу с ведущим дизайнером продукта, чтобы обсудить детали продуктов вашей компании.Это позволяет вам установить взаимопонимание и, в конечном итоге, вызвать у них энтузиазм по поводу предоставления услуг.

3. Ведение базы данных отдельных деталей

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

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

Во-вторых, как только у вас есть эти ссылки на базу данных отдельных деталей, все, что вам нужно сделать после ECO, — это обновить исходный файл. Эта корректировка будет распространяться на всю вашу техническую документацию.

4. Интеграция инженерных и проектных данных с базой данных деталей

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

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

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

Теги:
  • CAD
  • PLM
  • Обслуживание и запчасти

об авторе

Беверли Сполдинг

Беверли Сполдинг (Beverly Spaulding) — директор по формированию спроса в сервисных и розничных подразделениях PTC.Она выпускница Бостонского университета с опытом работы в области цифрового маркетинга, формирования спроса и маркетинга B2B. Ей нравятся технологии, данные и наука, лежащая в основе маркетинга.

Как изменится техническое письмо в следующие 10 лет?

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

Я вижу два заметных изменения по сравнению с 10-летней давностью:

Создание XML. Конечно, одним из основных изменений за последние 10 лет является повсеместное использование XML при создании технических документов. Два года назад Scriptorium Publishing (http://www.scriptorium.com) спросил более 600 технических писателей, пишут ли они в XML. Большинство респондентов либо уже писали на XML, внедряли его, планировали использовать, либо, по крайней мере, рассматривали его.Только 16% опрошенных не планировали его внедрять. Создание XML — это не прихоть. Он здесь, чтобы остаться.

Улучшенные инструменты. Я начал использовать FrameMaker 6.0 в конце 1990-х. Adobe только что выпустила версию 10 в январе. К счастью, разработка технической документации значительно улучшилась. Если вы раздаете PDF-документы экспертам в данной области, которые вносят правки в PDF-файлы, теперь мы можем импортировать эти изменения обратно в исходные файлы. Больше никакого утомительного редактирования. FrameMaker и RoboHelp могут иметь единый источник.Вы можете попросить профильных экспертов просмотреть ваши файлы через «облако».

Как технический текст изменится снова в следующие 10 лет? Вот несколько обоснованных предположений:

Мы все будем готовить онлайн-справку для мобильных устройств. Ожидается, что в ближайшем будущем смартфоны и планшеты начнут продавать больше компьютеров. Все больше и больше людей будут использовать эти устройства для работы, и им потребуется техническая помощь. Я ожидаю, что это следующая «большая вещь» для нас.

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

Социальные сети изменят то, как мы общаемся. На мой взгляд, большинство технических писателей не пользуются такими инструментами, как YouTube и Twitter. Но в ближайшие годы многие из нас поймут, как совместить социальные сети и техническую документацию. В апрельском номере журнала Intercom есть интересная статья под названием «Что такое справка 2.0 Революция ». Стоит проверить: www.stc.org. Издание тоже бесплатное.

Это некоторые из моих первых мыслей. Как, по вашему мнению, технический текст изменится в следующем десятилетии?

Блог Роберта Деспреса: http://www.robertdesprez.com/Site_3/Blog/Blog.html

Как писать техническую документацию

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

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

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

Что мы рассмотрим
  1. Как техническая документация может помочь снизить риск для вашего проекта (фактор шины)
  2. Основные элементы, которые необходимо включить при документировании проекта программного обеспечения
  3. Дополнительные темы, которые следует учитывать для более сложных и зрелых проектов
  4. Какие инструменты использовать при написании технической документации документация
  5. Как включить техническую документацию в бизнес-процесс, чтобы обеспечить ее выполнение

Что делать, если вашего разработчика сбит автобус?

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

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

И поверьте, ваши разработчики исчезнут со временем . Будем надеяться, что их не в буквальном смысле слова сбит автобус или какая-либо другая трагедия, но они, скорее всего, со временем перейдут на руководящую должность и потеряют связь с кодовой базой, перейдут в другую компанию или просто будут преследовать другие интересы. Если вы полагаетесь на одного человека, который знает, как работает ваше приложение, даже временные отъезды, такие как отпуск или отпуск по уходу за ребенком, могут привести к дорогостоящему застою в вашем проекте.

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

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

Минимум технической документации

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

  1. Source Control: Где находится исходный код и как получить к нему доступ, будь то GitHub, GitLab, BitBucket или где-то еще.
  2. Хостинг: Где размещено приложение и учетные данные. Это также должно включать такие вещи, как резервные копии, а также то, где зарегистрированы связанные домены и сертификаты SSL (если они отделены от основной учетной записи хостинга) и когда их необходимо продлить.
  3. Развертывание : Задокументируйте процесс развертывания новой версии продукта. Расскажите, насколько это автоматизировано, а не вручную, какие шаги и триггеры задействованы, как отлаживать неудачное развертывание и как при необходимости откатить изменения.
  4. Настройка среды разработки: Как получить локальную копию приложения и запустить ее на компьютере разработчика. Что необходимо установить, где что-то найти и как собрать, протестировать и получить доступ к приложению локально.Прохождение этого процесса — задача первого дня для новых разработчиков, поэтому его документирование поможет сэкономить время, когда вы расширяете свою команду.
  5. Важные службы и учетные данные : Для служб SaaS, таких как программное обеспечение для управления проектами, службы электронной почты (например, MailChimp), аналитика и т. Д. Убедитесь, что вы каталогизируете эти инструменты и способы доступа к ним.

Когда дело доходит до документирования учетных записей и паролей, я рекомендую использовать что-то вроде Google Sheet со следующими заголовками:

  • Название службы
  • URL для входа
  • Имя пользователя (если применимо)
  • Электронная почта
  • Стоимость
  • Заметки

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

Полезно иметь при себе техническую документацию

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

  1. Руководство по стилю кодирования: Задокументируйте свои стандарты для соглашений об именах, файловой структуры и организации кода, настроек линтера и общих правил стиля, относящихся к таким вещам, как фигурные скобки и отступы. Потраченное время на его формализацию добавляет большую ценность и приводит к тому, что разработчики создают чистый и непротиворечивый код, что ускоряет процесс проверки кода, что приводит к меньшему количеству возвращаемых задач.Основываясь на вашем руководстве и ссылаясь на существующий стандарт, такой как PHP PSR, можно сделать этот тип документации быстрым и безболезненным.
  2. Рабочий процесс разработки: Обсудите такие темы, как используемая методология управления проектами (SCRUM, Kanban и т. Д.), Как она выполняется и расписание встреч. Каков процесс от распределения задач до принятия и развертывания, и какие шаги необходимо выполнить на каждом этапе на этом пути. Также расскажите о стороне DevOps и о том, на каком уровне используется непрерывная интеграция / доставка / развертывание.
  3. Поток данных и соответствие нормативным требованиям: В зависимости от вашего помещения, местоположения и характера вашего проекта на вас могут распространяться такие нормативные акты, как COPA, GDPR, HIPAA или другие. Если это так, имеет смысл задокументировать, как вы соблюдаете эти стандарты и какие внутренние правила и процессы у вас есть, чтобы гарантировать, что вы это делаете. Кроме того, может быть целесообразно задокументировать ваши общие правила обработки данных и конфиденциальной информации в вашем приложении и какие шаги следует предпринять для обеспечения безопасности этой информации как в средах разработки, так и в производственной среде.

Все выше и выше

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

  1. Вспомогательные диаграммы: Создание визуальной документации, такой как диаграммы ER и блок-схемы, чтобы помочь прояснить, как ваше приложение работает на базовом уровне и как его различные модели связаны друг с другом.Это может быть особенно полезно в сложных приложениях, а также помогает быстро освоить новые разработки.
  2. Бизнес-логика: Если есть определенные алгоритмы, файлы или концепции, которые трудно понять даже с помощью встроенных комментариев кода, рассмотрите возможность создания для них дополнительной документации.
  3. Учебник по безопасности: Охватывает основные концепции, такие как внедрение SQL, XSS, CSRF и другие распространенные угрозы, относящиеся к вашему проекту. Укажите десятку лучших по OWASP и укажите любую информацию, касающуюся мер по снижению рисков и процессов безопасности, которые могут быть у вас на месте.Также укажите, как вы осуществляете контроль доступа к инфраструктуре, например использование белых списков и таких вещей, как SSH и ключи облачного хостинга.
  4. План аварийного восстановления: Документируйте, как справляться с перебоями в обслуживании, сбоями оборудования, потерей и повреждением данных, нарушениями безопасности, атаками программ-вымогателей и любыми другими потенциальными сценариями, которые вы можете придумать. Если у вас есть готовый план, вам будет легче отреагировать, если произойдет одно из этих событий.
  5. Дополнительные темы: Если у вас постоянно возникают разговоры о том, как выполнить определенную задачу разработки, как работает система или процесс, или вы не можете выполнять определенную бизнес-функцию из-за отсутствия кого-то, это признак того, что вы должны написать об этом документацию.

Программные средства документации

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

  1. README.md : стандартный источник информации, относящейся к любому проекту на основе git. Это может быть хорошей отправной точкой для базовой документации разработчика. Если он станет слишком большим, вы можете разбить его на несколько меньших файлов уценки.
  2. GitHub Wikis: для получения более подробной документации для разработчиков программного обеспечения. Подробнее о них читайте здесь .
  3. Shared Office Suite: Либо G Suite, либо Office 365. Воспользуйтесь функцией совместного использования, чтобы создать более надежную документацию как для разработчика, так и для операционной стороны вашего проекта. Может быть полезно иметь документ первичного указателя, который служит отправной точкой путем ссылки на каждый связанный тематический документ.
  4. Инструменты документации для конкретных технологий: , такие как Autodocs, для создания документации из кода или инструменты документации API, такие как Swagger.
  5. Корпоративные инструменты: для крупных организаций может быть полезно что-то вроде Atlassian Confluence, особенно если у вас разнообразный контент или вам необходимы расширенные средства управления разрешениями и функции совместной работы.

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

Готово

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

  1. Оправдывает ли это изменение обновление документации?
  2. Если да, обновлялась ли документация?

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

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

Сводка

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

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

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

Вам нужна помощь с вашим следующим программным проектом? Вы попали в нужное место. Каждый разработчик Scalable Path был тщательно отобран нашей технической командой по подбору персонала. Свяжитесь с нами, и мы в кратчайшие сроки подготовим вашу команду к работе.

.

Оставить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *