Реферат на тему «Документирование ПО»

Введение Один из важных этапов разработки программного обеспечения — создание документации. Документирование ПО (системная документация) помогает разработчикам и отделу сопровождения понять структуру системы и назначение ее элементов. Кроме того, часть документации (пользовательская документация) предназначена для конечных пользователей и администраторов — она позволяет понять, как нужно устанавливать и разворачивать систему, какие функции она предоставляет и каким образом можно бороться с ошибками, возникающими при ее работе. Документация по программному обеспечению представляет собой письменный текст или иллюстрацию, прилагаемую к компьютерному программному обеспечению или встроенную в исходный код. Документация либо объясняет, как работает программное обеспечение, либо как его использовать, и может означать разные вещи для людей, выполняющих разные роли. Актуальность данной работы обусловлена тем, что документация — важная часть разработки программного обеспечения, она либо объясняет, как работает программное обеспечение, либо как его использовать, и может означать разные вещи для людей, выполняющих разные роли. Д Целью данной работы рассмотрение актуальных вопросов документирования ПО. Задачи работы: 1. Рассмотрение понятия «Документирование ПО»; 2. Изучение классификации документирования ПО; 3. Анализ проблем и основных вопросов по документирования ПО.

Глава 1. ДОКУМЕНТИРОВАНИЕ ПО: ПОНЯТИЕ, КЛАССИФИКАЦИЯ

1.1. Что такое документирование ПО

Документа́ция на программное обеспечение — печатные руководства пользователя, диалоговая документация и справочный текст, описывающие, как пользоваться программным продуктом. Документация к современным системам доступна в нескольких форматах: Наиболее старый способ документирования — печатные документы (например, книги, посвященные определенному программному комплексу). Преимущество печатной документации — в легкости восприятия и (при адекватной организации) в упрощении поиска по неформальным запросам (когда известно, что ищется, но сложно сформулировать конкретные ключевые слова). Электронная документация, которая может быть локальной (например, Readme-файлы) или встраиваться в глобальную систему документации (man, help и так далее). По сравнению с печатной документацией, электронные документы могут быть более детальными; в них легче проводить поиск по ключевым словам. Документация, размещенная в Интернете. К этому виду документации относятся не только составленные разработчиками и размещенные на сайте продукта материалы (Getting started, справочные руководства и тому подобное), но и документы, генерируемые пользователями системы. К такой Web 2.0-документации относятся wiki по программным продуктам, записи в блогах, ответы на сайтах вроде stackoverflow и так далее. Документацию можно писать вручную с использованием систем редактирования и верстки (например, Microsoft Word или LaTeX). Более продуктивный способ — использование генераторов вроде Javadoc и Doxygen. В этом случае документирование осуществляется в исходных файлах программной системы, чаще всего в виде специальных комментариев (хотя возможны другие варианты, например, строки документации в Python). Такую документацию можно читать при просмотре исходного кода программы; она же используется для контекстной помощи в средах разработки. Наконец, при помощи генератора документацию можно выделить в отдельные документы (например, HTML или страницы man). Развитие идеи комментирования исходного кода программы — грамотное программирование (literate programming), придуманное Дональдом Кнутом для системы TeX. В этом подходе роли комментариев и кода меняются: текст программы представляет собой эссе на естественном языке с отдельными фрагментами кода. С помощью специальных инструментов код выделяется из эссе и формирует исходный код на определенном языке программирования; после этого можно проводить компиляцию и т.д. Грамотное программирование позволяет проследить ход мысли разработчика программы, лучше понять ее структуру и решения, принятые при разработке. При всех своих преимуществах, грамотное программирование применяется редко — не все программисты любят писать эссе [3, 23-28 c.].

1.2. Классификация документирования ПО

Существует классификация документов на программную систему: Некоторые документы (например, документ спецификации требований и планы проектирования / конструирования компонентов системы) описывают процессы разработки. Эти документы — часть системной документации. Остальные документы описывают продукты процессов разработки. Эти документы могут быть как системными (например, UML-схемы модулей системы), так и пользовательскими (например, руководства по использованию). Согласно гибкой методологии разработки, объем документации на систему, в особенности описывающей процессы, должен быть сведен к минимуму. На составление исчерпывающей документации уходит много времени и средств; из-за высокой скорости эволюции структура программной системы меняется настолько быстро, что документация устаревает практически сразу после выхода. Разумеется, полностью отказаться от документации нельзя: в любом случае сохраняется потребность в пользовательской документации, такой как руководства. Существует четыре основных типа документации на ПО: • архитектурная/проектная; • техническая; • пользовательская; • маркетинговая. Архитектурная/проектная документация Проектная документация, предназначенная для утверждения (Стадия «Проект», утверждаемая часть рабочего проекта) — документация, содержащая архитектурно-градостроительные решения, учитывающие социальные, экономические, функциональные, инженерные, технологические, противопожарные, санитарно-гигиенические, экологические, архитектурно-художественные и иные требования к объекту, в объеме. Проектная документация разрабатывается на основании исходно-разрешительной документации в соответствии с требованиями строительных норм, архитектурно-планировачного задания и задания на проектирование [2, 73-84 c.]. Техническая документация Техническая документация — это документация, которая используется при проектировании, изготовлении и эксплуатации каких-либо технических объектов: зданий, сооружений, промышленных товаров, программного и аппаратного обеспечения. Техническую документацию разделяют на несколько видов: • конструкторская документация • эксплуатационная документация • ремонтная документация • технологическая документация • документы, определяющие технологический цикл изделия • документы, дающие информацию, необходимую для организации производства и ремонта изделия Технической документацией также может называться технические условия, технический паспорт, техническое руководство или техническая литература. Кроме того, существуют более узко применимые документы, устанавливающие специфические требования. К таким можно отнести паспорта безопасности, расчет калорийности и некоторые другие. Техническая документация наглядно демонстрирует и позволяет проследить правильность хода процесса, своевременно выявить отклонения или сбои и предупредить выпуск некачественной продукции или выполнение услуг. Также техническая документация необходима при оформлении договоров, сертификатов соответствия и при прохождении инспекционных проверок в компании надзорными органами. В производстве продукции существуют следующие виды технической документации – спецификация, паспорт качества, технические условия (ТУ), которые необходимо зарегистрировать в надзорных органах [4, 66-74 c.]. Пользовательская документация Пользовательская документация ПО — объясняет пользователям, как они должны действовать, чтобы применить разрабатываемое ПО. Она необходима, если ПО предполагает какое-либо взаимодействие с пользователями. К такой документации относятся документы, которыми должен руководствоваться пользователь при инсталляции ПО, при применении ПО для решения своих задач и при управлении ПО (например, когда разрабатываемое ПО будет взаимодействовать с другими системами). В связи с этим следует различать две категории пользователей ПО: 1. Ординарных пользователей ПО 2. Администраторов ПО. Обычный пользователь программы — использует программу для решения своих задач. Он может не знать многих деталей работы компьютера или принципов программирования. Администратор программного обеспечения — управляет использованием программного обеспечения обычными пользователями и поддерживает программное обеспечение, не связанное с модификацией программного обеспечения. Например, он может регулировать права доступа к программному обеспечению между обычными пользователями, связываться с поставщиками программного обеспечения или предпринимать определенные действия для поддержания работы программного обеспечения, когда оно является частью другой системы. Состав пользовательской документации зависит от целевой группы пользователей. Целевая группа здесь относится к контингенту пользователей программного обеспечения, которым требуется специальная пользовательская документация по программному обеспечению. Пользовательская документация должна содержать информацию, необходимую для каждой аудитории. То, как документ используется, относится к тому, как документ используется. Обычно пользователю достаточно больших программных комплексов документы нужны либо для изучения ПО (использование в качестве руководства), либо для уточнения некоторой информации (использование в качестве справочника).

Глава 2. ПРОБЛЕМЫ И ОСНОВНЫЕ ВОПРОСЫ ПО ДОКУМЕНТИРОВАНИЮ ПО

2.1. Проблемы стандартов единой системы программной документации

Основу отечественной нормативной базы в области документирования ПС составляет комплекс стандартов Единой системы программной документации (ЕСПД). Основная и большая часть комплекса ЕСПД была разработана в 70-е и 80-е годы 20 века. Сейчас этот комплекс представляет собой систему межгосударственных стандартов стран СНГ (ГОСТ), действующих на территории Российской Федерации на основе межгосударственного соглашения по стандартизации [5, 17-23 c.]. Единая система программной документации — это комплекс государственных стандартов, устанавливающих взаимоувязанные правила разработки, оформления и обращения программ и программной документации. Стандарты ЕСПД в основном охватывают ту часть документации, которая создается в процессе разработки ПС, и связаны, по большей части, с документированием функциональных характеристик ПС. Следует отметить, что стандарты ЕСПД (ГОСТ 19) носят рекомендательный характер. Впрочем, это относится и ко всем другим стандартам в области ПС (ГОСТ 34, международному стандарту ISO/IEC и др.). Дело в том, что в соответствии с Законом РФ «О стандартизации» эти стандарты становятся обязательными на контрактной основе, т.е. при ссылке на них в договоре на разработку (поставку) ПС. В состав ЕСПД входят: • основополагающие и организационно-методические стандарты; • стандарты, определяющие формы и содержание программных документов, применяемых при обработке данных; • стандарты, обеспечивающие автоматизацию разработки программных документов. Говоря о состоянии ЕСПД в целом, можно констатировать, что большая часть стандартов ЕСПД морально устарела.

2.2. Основные недостатки ЕСПД

К числу основных недостатков ЕСПД можно отнести: • ориентацию на единственную «каскадную» модель жизненного цикла ПС; • отсутствие четких рекомендаций по документированию характеристик качества ПС; • отсутствие системной увязки с другими действующими отечественными системами стандартов по ЖЦ и документированию продукции в целом, например ЕСКД; • нечетко выраженный подход к документированию ПС как товарной продукции; • отсутствие рекомендаций по самодокументированию ПС, например, в виде экранных меню и средств оперативной помощи пользователю (хелпов); • отсутствие рекомендаций по составу, содержанию и оформлению перспективных документов на ПС, согласованных с рекомендациями международных и региональных стандартов. ЕСПД нуждается в полном пересмотре на основе стандарта ИСО/МЭК 12207-95 на процессы жизненного цикла ПС [1]. При этом стиль применения стандартов может соответствовать современному общему стилю адаптации стандартов к специфике проекта: заказчик и руководитель проекта выбирают уместное в проекте подмножество стандартов и ПД, дополняют выбранные ПД нужными разделами и исключают ненужные, привязывают создание этих документов к той схеме ЖЦ, которая используется в проекте. Надо сказать, что наряду с комплексом ЕСПД официальная нормативная база РФ в области документирования ПС и в смежных областях включает ряд перспективных стандартов (отечественного, межгосударственного и международного уровней). Международный стандарт ISO/IEC 12207:1995 на организацию ЖЦ продуктов программного обеспечения (ПО), казалось бы, весьма неконкретный, но вполне новый и отчасти «модный» стандарт. Стандарты комплекса ГОСТ 34 на создание и развитие автоматизированных систем — обобщенные, но воспринимаемые как весьма жесткие по структуре ЖЦ и проектной документации. Но эти стандарты многими считаются бюрократическими до вредности и консервативными до устарелости.

2.3. Актуальные вопросы при разработке документации ПО

В любом случае актуальными при разработке технической документации для программного обеспечения будут такие основные вопросы: • Какова нормативная база и как её следует применять? • Какая именно документация нужна среди огромного количества документов? В настоящее время действуют следующие стандарты документирования: ГОСТ 19.201 (Единая система программной документации (ЕСПД); ГОСТ 2.015-2013 (Единая система конструкторской документации (ЕСКД); ГОСТ 34.602 (Комплекс стандартов на автоматизированные системы (КСАС). Указанные стандарты с 2006 года применять не обязательно. В соответствии с нормами Федерального закона № 184-ФЗ «О техническом регулировании» вместо стандартов применяются специально разработанные технические регламенты. Но ГОСТы по-прежнему нужно применять при разработке документации для государственных заказчиков, а также для крупных организаций (особенно с государственным участием). Последние, как правило, разрабатывают собственные стандарты на основе указанных ГОСТов [7, 110-121 c.]. Следует также помнить, что в соответствии с ФЗ «О техническом регулировании» национальные стандарты имеют всегда приоритет над международными. То есть, использовать международные стандарты можно лишь в случаях, если последние не противоречат национальным! Благо, свободы действий отечественные стандарты предоставляют намного больше зарубежных. Последние пересматриваются каждые 5-7 лет и характеризуются большей конкретизацией, но отображают весь актуальный опыт за указанный период времени. Отечественные же (не имея столь разработанной конкретики) характеризуются глубокой разработкой концептуальных моментов. Это позволяет создавать на их основе неплохие стандарты в соответствии с требованиями времени.

2.4. Перечень документов ЕСПД

ГОСТ 19.001-77. ЕСПД. Общие положения. ГОСТ 19.002-80. ЕСПД. Схемы алгоритмов и программ. Правила выполнения. — Заменен на ГОСТ 19.701-90 ГОСТ 19.003-80. ЕСПД. Схемы алгоритмов и программ. Обозначения условные графические. — Заменен на ГОСТ 19.701-90 ГОСТ 19.004-80. ЕСПД. Термины и определения. — Заменен на ГОСТ 19781-90 ГОСТ 19.005-85. ЕСПД. Р-схемы алгоритмов и программ. Обозначения условные графические и правила выполнения. ГОСТ 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. ЕСПД. Общие правила дублирования, учета и хранения.

Заключение

Документация является органической, составной частью программного продукта для ЭВМ и требуются значительные ресурсы для ее создания и применения. Тексты и объектный код программ для ЭВМ могут стать программным продуктом только в совокупности с комплексом документов, полностью соответствующих их содержанию и достаточных для его освоения, применения и изменения. Для этого документы должны быть корректными, строго адекватными текстам программ и содержанию баз данных – систематически, структурировано и понятно изложены, для возможности их успешного освоения и использования достаточно квалифицированными специалистами различных рангов и назначения. Качество и полнота отображения в документах процессов и продуктов в жизненном цикле программных средств должны полностью определять достоверность информации для взаимодействия заказчиков, пользователей и разработчиков, а тем самым, корректность функций и достигаемое качество программных продуктов и соответствующих систем. Посредством документов (электронных или бумажных) специалисты взаимодействуют с программными средствами и данными в реализующих их вычислительных машинах, а также между собой. Существует большая разница между тем, чтобы просто написать и запрограммировать некоторую функцию для индивидуального использования её разработчиком, и тем, чтобы изготовить её как качественный программный продукт, отчуждаемый от разработчиков, поставляемый заказчику и пользователям. Создание программного продукта требует значительных организационных усилий, ибо её документация – это сложный живой организм, подверженный постоянным изменениям, которые могут вноситься многими специалистами. Управление документацией должно непрерывно поддерживать её полноту, корректность и согласованность с программным продуктом. Необходимо обеспечивать возможность достоверного, формально точного общения всех участников проекта ПС между собой, с создаваемым продуктом и с документами для гарантии поступательного развития, совершенствования и применения комплекса программ. Адекватность документации требованиям, состоянию текстов и объектных кодов программ должна инспектироваться и удостоверяться (подписываться) ответственными руководителями и заказчиками проекта. Ошибки и дефекты документов не менее опасны для применения ПС, чем ошибки в структуре, интерфейсах, файлах текстов программ и в содержании данных. Поэтому к разработке, полноте, корректности и качеству документации необходимо столь же тщательное отношение, как к разработке и изменениям текстов программ и данных.

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

1. ГОСТ 19.001-77. ЕСПД. Общие положения. 2. Гниденко, И. Г. Технология разработки программного обеспечения: учеб. пособие для СПО / И. Г. Гниденко, Ф. Ф. Павлов, Д. Ю. Федоров. — М.: Издательство Юрайт, 2017. — 235 с. 3. Гордеев, А. В. Системное программное обеспечение / А.В. Гордеев, А.Ю. Молчанов. — М.: Питер, 2016. — 736 c. 4. Джордж Хайнеман, Гэри Поллис, Стэнли Селков. Алгоритмы. Справочник с примерами на C, C++, Java и Python. – М.: Вильямс, 2017. – 432 с. 5. Майерс, Г. Надежность программного обеспечения / Г. Майерс. — М.: Мир, 2018. — 360 c. 6. Макаровских Т.А. Документирование программного обеспечения. В помощь техническому писателю. Учебное пособие. – М.: Ленанд, 2017. – 266 с. 7. Мамонова, Т. Е. Информационные технологии. Лабораторный практикум: учеб. пособие для СПО / Т. Е. Мамонова. — М.: Издательство Юрайт, 2019. — 178 с. 8. Перлова, О.Н. Проектирование и разработка информационных систем: Учебник / О.Н. Перлова. — М.: Академия, 2018. — 272 c.