Техническая документация является составляющей проекта по созданию, внедрению, сопровождению, модернизации и ликвидации информационной системы на всем протяжении жизненного цикла.
Комплекс технических документов, который регламентирует деятельность разработчиков, называется нормативно-методическим обеспечением (НМО). В данный комплекс входят:
ü руководящие документы;
ü методики и положения;
ü инструкции и т. д.
Основным назначением технической документации является обеспечение эффективных процедур разработки и использования информационной системы как программного продукта, а также организация обмена между разработчиками и пользователями ИС.
Таким образом, можно выделить следующие функции технической документации:
ü дает описание возможностей системы;
ü обеспечивает фиксацию принятых и реализованных проектных решений;
ü определяет условия функционирования ИС;
ü предоставляет информацию об эксплуатации и обслуживании ИС;
ü регламентирует процедуру защиты информации, регулирует права различных групп пользователей;
Техническая документация. Виды технической документации
ü определяет возможности модернизации системы.
Перед составлением технической документации необходимо иметь ответы на следующие вопросы:
ü что и зачем должно быть документировано?
ü для кого предназначен тот или иной документ?
ü какие ошибки может допустить пользователь и что нужно сделать для их устранения?
ü как и в каких условиях будет использоваться документ?
ü каковы сроки разработки документа?
ü как будет обновляться и поддерживаться документация, каковы механизмы и сроки внесения изменений и пересмотра документов и кто ответственен за реализацию этих действий, а также за хранение, неизменность и контроль за исполнением?
ü кто будет оценивать документ и как он соотносится с отраслевыми или ведомственными требованиями на сертификацию разработки?
Ответы на эти вопросы должны быть получены на ранних стадиях разработки информационной системы и входить в состав разрабатываемой в рамках проекта документации.
Как правило, к технической документации предъявляются следующие основные требования:
ü документы должны быть точными, полными и, по возможности, краткими, иметь четкое и однозначное толкование;
ü документация должна создаваться параллельно с разработкой самой информационной системы;
ü обязанности по документированию системы лежат на ее разработчике;
Исходя из последнего требования к документации, необходимо рассмотреть основные стандарты, которые используются в области информационных систем на территории Российской Федерации.
В настоящее время существует несколько классификаций стандартов на проектирование и разработку информационных (автоматизированных) систем. Классический способ классификации группирует стандарты по двум признакам.
По объекту стандартизации:
ü стандарты на продукты и услуги;
ü стандарты на процессы и технологии.
По предмету стандартизации:
Почему техническая документация — это интересно
ü функциональные стандарты (стандарты на языки программирования, протоколы, интерфейсы);
ü стандарты на организацию жизненного цикла (ЖЦ) автоматизированных систем и программного обеспечения.
Альтернативная классификация группирует стандарты по статусу:
ü официальные стандарты;
ü стандарты «де-факто».
В свою очередь официальные стандарты подразделяются на:
þ международные стандарты (ISO, ANSI, IDEF0/1);
þ стандарты Российской Федерации (ГОСТ);
þ отраслевые стандарты;
þ ведомственные стандарты.
Стандартами «де-факто» являются официально никем не утвержденные, но фактически действующие стандарты.
Как правило, в каждую из этих групп входят документы, существенно разные по степени обязательности для организаций, конкретности и детализации содержащихся требований, открытости и гибкости, а также адаптируемости к конкретным условиям.
Отдельно выделяют корпоративные стандарты.
Для большинства сложных проектов приходится создавать свои комплексы нормативных и методических документов, регламентирующих процессы, этапы, работы и документы конкретных программных продуктов. Такие стандарты называют корпоративными и представляют собой соглашение о единых правилах организации технологии или управления в организации. К таким стандартам относятся:
ü стандарты проектирования;
ü стандарты оформления проектной документации;
ü стандарты пользовательского интерфейса.
Стандарт проектирования должен устанавливать:
þ набор необходимых моделей (диаграмм) на каждой стадии проектирования и степень их детализации;
þ правила именования объектов, оформления диаграмм, включая требования к форме и размерам объектов и т. д.
þ требования к конфигурации рабочих мест разработчиков, включая настройки операционной системы;
þ правила интеграции подсистем проекта, правила поддержания проекта в одинаковом для всех разработчиков состоянии, правила проверки проектных решений на непротиворечивость.
Стандарт оформления проектной документации должен устанавливать:
þ комплектность, состав и структуру документации на каждой стадии проектирования;
þ требования к ее оформлению, включая требования к содержанию разделов, подразделов, пунктов, таблиц и т. д.
þ правила подготовки, рассмотрения, согласования и утверждения документации с указанием предельных сроков для каждой стадии;
þ требования к настройке издательской системы, используемой в качестве встроенного средства подготовки документации;
þ требования к настройке CASE-средств для обеспечения подготовки документации в соответствии с установленными требованиями.
Стандарт интерфейса пользователя должен устанавливать:
þ правила оформления экранов (шрифты и цветовая палитра), состав и расположение окон и элементов управления;
þ правила использования клавиатуры и мыши;
þ правила оформления текстов помощи;
þ перечень стандартных сообщений;
þ правила обработки реакции пользователя.
За основу корпоративных стандартов могут приниматься отраслевые, национальные или международные стандарты. Сюда могут относиться различные методические материалы ведущих фирм-разработчиков ПО, научных центов, фирм-консультантов, консорциумов по стандартизации.
Отечественными стандартами являются стандарты ЕСПД (Единой Системы Программной Документации) серии ГОСТ 19.ХХХ и комплекс стандартов на автоматизированные системы серии ГОСТ 34.ХХХ, созданные в 80-90-е годы двадцатого века. Кроме того, существуют более современные стандарты на программное обеспечение.
Перечень стандартов ГОСТ 19.ХХХ
Единая Система Программной Документации
ü ГОСТ 19.001-77 Общие положения
ü ГОСТ 19.101-77 Виды программ и программных документов
ü ГОСТ 19.102-77 Стадии разработки
ü ГОСТ 19.103-77 Обозначения программ и программных документов
ü ГОСТ 19.104-78 Основные надписи
ü ГОСТ 19.105-78 Общие требования к программным документам
ü ГОСТ 19.106-78 Требования к программным документам, выполненным печатным способом
ü ГОСТ 19.201-78 Техническое задание, требования к содержанию и оформлению
ü ГОСТ 19.202-78 Спецификация. Требования к содержанию и оформлению
ü ГОСТ 19.301-79 Программа и методика испытаний. Требования к содержанию и оформлению
ü ГОСТ 19.401-78 Текст программы. Требования к содержанию и оформлению
ü ГОСТ 19.402-78 Описание программы
ü ГОСТ 19.403-79 Ведомость держателей подлинников
ü ГОСТ 19.404-79 Пояснительная записка. Требования к содержанию и оформлению
ü ГОСТ 19.501-78 Формуляр. Требования к содержанию и оформлению
ü ГОСТ 19.502-78 Описание применения. Требования к содержанию и оформлению
ü ГОСТ 19.503-79 Руководство системного программиста. Требования к содержанию и оформлению
ü ГОСТ 19.504-79 Руководство программиста. Требования к содержанию и оформлению
ü ГОСТ 19.505-79 Руководство оператора. Требования к содержанию и оформлению
ü ГОСТ 19.506-79 Описание языка. Требования к содержанию и оформлению
ü ГОСТ 19.507-79 Ведомость эксплуатационных документов
ü ГОСТ 19.508-79 Руководство по техническом обслуживанию. Требования к содержанию и оформлению
ü ГОСТ 19.601-78 Общие правила дублирования, учета и хранения
ü ГОСТ 19.602-78 Правила дублирования, учета и хранения программных документов, выполненных печатным способом
ü ГОСТ 19.603-78 Общие правила внесения изменений
ü ГОСТ 19.604-78 Правила внесения изменений в программные документы, выполненных печатным способом
Стандарты ЕСПД практически не имеют содержательной составляющей и дают формальные требования к составу, содержанию и оформлению документов, описывающих программу на разных стадиях ее жизненного цикла.
Комплекс ГОСТ 34 задумывался как всеобъемлющий комплекс взаимоувязанных межотраслевых документов и рассчитанный на взаимодействие заказчика и разработчика. Он должен был разрешить проблему «вавилонской башни», при которой в различных отраслях и областях деятельности использовалась плохо согласованная или несогласованная нормативно-техническая документация. Объектами стандартизации являются автоматизированные системы различных видов и все виды их компонентов, а не только программное обеспечение и базы данных. Комплекс рассчитан на взаимодействие заказчика и разработчика, при этом в нем предусмотрено, что заказчик может разрабатывать систему для себя сам.
Перечень стандартов ГОСТ 34.ХХХ
Стандарты информационной технологии
ü ГОСТ 34.003-90 Информационная технология (ИТ). Комплекс стандартов на автоматизированные системы. Автоматизированные системы. Термины и определения
ü ГОСТ 34.201-89 Информационная технология (ИТ). Комплекс стандартов на автоматизированные системы. Виды, комплектность и обозначения документов при создании автоматизированных систем
ü ГОСТ 34.320-96 Информационные технологии (ИТ). Система стандартов по базам данных. Концепции и терминология для концептуальной схемы и информационной базы
ü ГОСТ 34.321-96 Информационные технологии (ИТ). Система стандартов по базам данных. Эталонная модель управления данными
ü ГОСТ 34.601-90 Информационная технология (ИТ). Комплекс стандартов на автоматизированные системы. Автоматизированные системы. Стадии создания
ü ГОСТ 34.602-89 Информационная технология (ИТ). Комплекс стандартов на автоматизированные системы. Техническое задание на создание автоматизированной системы
ü ГОСТ 34.603-92 Информационная технология (ИТ). Виды испытаний автоматизированных систем
ü РД 50-34.698-90 Методические указания. Информационная технология. Комплекс стандартов и руководящих документов на автоматизированные системы. Автоматизированные системы. Требования к содержанию документов
Многие авторы считают эти стандарты морально устаревшими, однако ими продолжают активно пользоваться при оформлении проектной документации. Если разрабатывается документация на программу (систему), созданную под конкретную организацию, следует воспользоваться требованиями ГОСТов 34. Если разрабатывается документация на программу массового применения, то следует использовать ГОСТы серии 19.
Если говорить о более поздних отечественных стандартах, следует выделить ГОСТ Р 51904-2002 Программное обеспечение встроенных систем. Общие требования к разработке и документированию, который был разработан Государственным научно-исследовательским институтом авиационных систем с участием Научно-исследовательского института стандартизации и унификации.
Данный стандарт распространяется на процессы разработки и документирования программного обеспечения встроенных систем реального времени и все действия, имеющие отношение к разработке программного обеспечения. Стандарт подготовлен в развитие ГОСТ Р ИСО/МЭК 12207 Информационная технология. Системная и программная инженерия. Процессы жизненного цикла программных средств, о котором пойдет речь в п. 2.3.
Отдельно стандарт ГОСТ Р 51904-2002 в части подготовки документов будет рассмотрен в главе 9 «Программное обеспечение».
Международные стандарты применяются для разработки документации международного уровня. Как правило, они не бесплатные, так как разрабатываются не государственными организациями, но, в отличие от отечественных, разработаны недавно.
В основе практически всех современных промышленных технологий создания программных средств лежит международный стандарт ISO/IEC 12207 Information technology. System and software engineering. Software life cycle processes (ГОСТ Р ИСО/МЭК 12207-2010 Информационная технология. Системная и программная инженерия. Процессы жизненного цикла программных средств).
Первая редакция стандарта ISO/IEC 12207 была опубликована в августе 1995 г. и явилась первым международным стандартом, содержавшим представительный набор процессов жизненного цикла в отношении программного обеспечения, которое рассматривалось как часть большой системы, а также применительно к программным продуктам и услугам. Стандарт определяет процессы, виды деятельности и задачи, которые используются при приобретении программного продукта или услуги, а также при поставке, разработке, применении по назначению, сопровождении и прекращении применения программных продуктов.
Основными характеристиками данного стандарта являются:
ü динамичность: один процесс при необходимости вызывает другой или его часть, что позволяет реализовать любую модель жизненного цикла;
ü адаптивность: стандарт предусматривает исключение процессов, видов деятельности и задач, неприменимых в конкретном проекте.
Кроме того, существуют международные стандарты (на английском языке), которые направлены на написание документации:
1. IEEE Std 1063-2001 «IEEE Standard for Software User Documentation» – стандарт для написания руководства пользователя. В документе обозначены требования к структуре, содержимому и формату инструкций пользователя.
2. IEEE Std 1016-1998 «IEEE Recommended Practice for Software Design Descriptions» – стандарт для написания технического описания программы. Представлены рекомендации к документам, описывающим архитектуру программного обеспечения.
3. ISO/IEC FDIS 18019:2004 «Guidelines for the design and preparation of user documentation for application software» – стандарт для написания руководства пользователя. В данном документе есть большое количество примеров. Также в приложениях есть чек-листы «что не забыть сделать в процессе разработки документации» и «что должно быть».
Документ особенно полезен начинающим специалистам.
4. ISO/IEC 26514:2008 «Requirements for designers and developers of user documentation» – стандарт для дизайнеров и разработчиков пользователей документации.
Международных стандартов довольно много, в каждой стране они свои, так как один и тот же стандарт не всегда может подойти и европейским, и азиатским компаниям.
Источник: mti58.ru
Техническая документация
Техническая документация — это документация, которая используется при проектировании , изготовлении и эксплуатации каких-либо технических объектов: зданий, сооружений, промышленных товаров, программного и аппаратного обеспечения.
Техническую документацию разделяют на несколько видов:
- конструкторская документация
- эксплуатационная документация
- ремонтная документация
- технологическая документация
- документы, определяющие технологический цикл изделия
- документы, дающие информацию, необходимую для организации производства и ремонта изделия
Технической документацией также может называться технические условия, технический паспорт, техническое руководство или техническая литература.
Кроме того существуют более узко применимые документы, устанавливающие специфические требования. К таким можно отнести паспорта безопасности, расчет калорийности и некоторые другие.
Техническая документация наглядно демонстрирует и позволяет проследить правильность хода процесса, своевременно выявить отклонения или сбои и предупредить выпуск некачественной продукции или выполнение услуг. Также техническая документация необходима при оформлении договоров, сертификатов соответствия и при прохождении инспекционных проверок в компании надзорными органами.
В производстве продукции существуют следующие виды технической документации – спецификация, паспорт качества, технические условия (ТУ), которые необходимо зарегистрировать в надзорных органах
Опытные эксперты Российского Сертификационного Центра осуществляют разработку технической документации строго в соответствии с требованиями действующих нормативных документов: Технических регламентов Таможенного Союза, ГОСТ 2 «Единая система конструкторской документации», Стандартов международной организации по стандартизации (ISO), Внутренних стандартов клиента
Техническая документация делиться на несколько видов:
Расчет энергетической ценности
Источник: rossertcentr.ru
Техническая документация в разработке ПО: кто, зачем, когда и как описывает проект
Привет! Меня зовут Даша Григорьева, я технический писатель в компании 65apps. Мы занимаемся разработкой сложных мобильных решений, и моя задача — подготовка технической документации по проектам. Очень часто роль технического писателя бывает недооцененной в компании (не у нас, конечно). Поэтому я хочу рассказать, зачем компании-разработчику нужен такой специалист, что такое технический проект, чем он отличается от ТЗ и почему это все необходимо для разработки мобильного приложения.
Общаясь с большим количеством компаний, я все еще встречаю твердое убеждение в том, что написание технического задания для разработки ПО — пустая трата времени и денег. Мы в 65apps считаем иначе. Поэтому приведу несколько аргументов в пользу технической документации и расскажу, кто и как ее пишет.
Техническая документация позволяет оценить стоимость разработки и согласовать функциональность будущей системы. При возникновении споров о стоимости и сроках разработки той или иной фичи она может стать определенной гарантией для заказчика. С другой стороны, если возникнет потребность в развитии приложения, документация облегчит процесс доработки и даст четкое понимание, возможно ли встроить новую функциональность в существующую систему.
Другой пример — государственные организации или организации, чья деятельность ограничивается или подчиняется законам и надзорным органам. Они обязаны осуществлять разработку ПО по всем правилам и с соблюдением всех стандартов. В таких проектах техническая документация, подготовленная по ГОСТам, — необходимое условие.
И разумеется, грамотно составленная и актуальная документация необходима для того, чтобы каждый участник в процессе разработки мог обращаться к документам, если возникают вопросы по конкретной задаче или по всей системе в целом.
Техническое задание и технический проект — два разных документа. Техническое задание отвечает на вопрос «что нужно сделать?», его составляет аналитик в самом начале проекта. Технический проект разрабатывает технический писатель. Этот документ создается после ТЗ и отвечает на вопрос «как нужно делать?».
Кто пишет техническую документацию
Обычно разработкой ТЗ занимается аналитик. Именно он общается с заказчиком / заинтересованным лицом и выявляет у него требования. В сложных случаях к процессу можно привлечь менеджера проекта, разработчиков, тестировщиков и других специалистов. Чем сложнее проект — тем больше требований к документации.
Серьезные заказчики из крупных корпораций и госсектора требуют составлять документацию в соответствии с ГОСТами, а это задача очень трудоемкая, требующая внимательности к деталям и постоянной вовлеченности в процесс. И это не только ТЗ, но и технический проект, полностью описывающий все используемые в разработке решения, подходы и методологии. На него также распространяются ГОСТы. Подготовкой такой документации должен заниматься специалист — технический писатель.
Для крупных проектов иметь в штате технического писателя просто необходимо. Разработка решений для крупных заказчиков может длиться год и более, это довольно долгий срок. За это время возникает достаточное количество изменений, провоцирующих обновление документации. Кроме того, любая долгосрочная разработка ПО предполагает развитие. В этом случае актуальная техническая документация позволит снизить риски, закладываемые в работу исполнителей.
Исключение может быть сделано для представителей госсектора. Таким организациям необязательно иметь в своем штате специалистов соответствующего профиля, так как при возникновении необходимости всегда можно обратиться к профессионалам, которые выполнят качественно свою работу.
Кто такой технический писатель
Строго сформулированного перечня должностных обязанностей технического писателя не существует: каждая компания формирует его сама, а иногда возлагает на такого специалиста и дополнительные задачи. Поэтому иногда бывает сложно даже определить род деятельности технического писателя. В нашей компании такой специалист составляет документацию, необходимую для дальнейшей разработки программного обеспечения.
Для этого он собирает информацию и материалы от участников проекта и документирует эти данные согласно требованиям заказчика, в том числе и в соответствии с ГОСТами. Речь идет о ГОСТ 19 «Единая система программной документации» и ГОСТ 34 «Информационная технология. Комплекс стандартов на автоматизированные системы». Также технический писатель следит за актуальностью технической информации, если это необходимо на длительных и сложных проектах.
Какая техническая документация нужна разработчику
Рассмотрим идеальный с точки зрения ГОСТа процесс разработки системы.
Все начинается с требований заказчика или заинтересованных лиц, которые необходимо выявить и обязательно зафиксировать в документе «Техническое задание».
Техническое задание — это документ, регламентирующий бизнес-цели, общее описание системы, объем работ, границы проекта, а также порядок разработки, оценки и приемки. Данный документ отвечает нам на вопрос «что нужно сделать?» и фактически является постановкой задачи.
Аналитик составляет ТЗ и согласует его со всеми заинтересованными сторонами. После того как собраны и утверждены все требования, можно приступать к созданию прототипов будущей системы и разработке программного обеспечения.
На этом этапе начинается разработка макетов, сценариев, архитектуры и др. Раз уж мы говорим об эталонном процессе разработки, то все это должно быть описано в техническом проекте, который также использует часть информации из ТЗ.
Технический проект — это совокупность документов, описывающих и обосновывающих все подходы, методы, архитектурные и технические решения, применяемые для создания системы. Например, в технический проект включают макеты интерфейсов, описание протоколов для интеграции со смежными системами и оборудованием, пользовательские сценарии, описание алгоритма и их формирование, структура серверов и баз данных, а также другие требования к системе и ее взаимодействию с другими внешними системами.
это далеко не все: существует много стандартов для написания технической документации, и для каждой страны они свои. В отечественных стандартах есть отдельно ГОСТ на создание автоматизированных работ и на программное изделие. Например, технический проект по ГОСТу 19 «Единая система программной документации» может включать в себя следующий перечень работ:
- уточнение структуры входных и выходных данных,
- разработка алгоритма решения задачи,
- определение формы представления входных и выходных данных,
- определение семантики и синтаксиса языка,
- разработка структуры программы,
- окончательное определение конфигурации технических средств,
- разработка плана мероприятий по разработке и внедрению программ,
- разработка пояснительной записки,
- согласование и утверждение технического проекта.
Теперь, когда есть четкое понимание архитектуры, функциональности и дизайна проекта, можно перейти к разработке системы и ее тестированию.
На этапе тестирования, помимо проверки работоспособности системы, проверяется также выполнение всех требований, зафиксированных в документах, что позволяет разрешить спорные ситуации с заказчиком.
Когда составлять техническую документацию
Выше я описала идеальный процесс создания программного обеспечения, но иногда некоторые документы технического проекта составляют уже после этапа разработки.
Есть проекты, в которых важно иметь полную документацию до начала работ. Это касается решений с высокими требованиями к безопасности, соблюдению законодательства и т. д. Например, мобильные приложения для банков. В этом случае важно сначала продумать все детали системы (информационная безопасность клиентов и самого банка, соответствие законам). На это уйдет больше времени, но позволит избежать финансовых и репутационных рисков.
Если разработка идет по методологии Agile, то нет смысла прописывать всю документацию до старта работ. Если заказчику важно работать по спринтам и контролировать ход разработки, документацию можно дописывать параллельно основному процессу.
В нашей компании возможны оба варианта — мы умеем адаптироваться под условия и пожелания заказчика.
На сегодняшний день технический писатель не самая распространенная специальность, но для серьезной компании-разработчика такой сотрудник не менее важен, чем, например, аналитик.
Техническая документация обязательно разрабатывается для госзаказчиков, она необходима и для долгосрочных проектов, на которых с бОльшей вероятностью могут меняться подрядчики. Имеет смысл создавать технический проект для ноу-хау технологий и проектов высокой сложности — документация понадобится отделу QA, чтобы отличить баги и фич.
- технический писатель
- техническое задание
- техническая документация
- Управление разработкой
- Подготовка технической документации
Источник: habr.com