Введение Один из важных этапов разработки программного обеспечения — создание документации. Документирование ПО (системная документация) помогает разработчикам и отделу сопровождения понять структуру системы и назначение ее элементов.
Кроме того, часть документации (пользовательская документация) предназначена для конечных пользователей и администраторов — она позволяет понять, как нужно устанавливать и разворачивать систему, какие функции она предоставляет и каким образом можно бороться с ошибками, возникающими при ее работе. Документация по программному обеспечению представляет собой письменный текст или иллюстрацию, прилагаемую к компьютерному программному обеспечению или встроенную в исходный код.
Документация либо объясняет, как работает программное обеспечение, либо как его использовать, и может означать разные вещи для людей, выполняющих разные роли. Актуальность данной работы обусловлена тем, что документация — важная часть разработки программного обеспечения, она либо объясняет, как работает программное обеспечение, либо как его использовать, и может означать разные вещи для людей, выполняющих разные роли. Д Целью данной работы рассмотрение актуальных вопросов документирования ПО. Задачи работы: 1. Рассмотрение понятия «Документирование ПО»; 2. Изучение классификации документирования ПО; 3. Анализ проблем и основных вопросов по документирования ПО.
Dr.Explain — Захват и автоматическое документирование окна программы
Глава 1. ДОКУМЕНТИРОВАНИЕ ПО: ПОНЯТИЕ, КЛАССИФИКАЦИЯ
1.1. Что такое документирование ПО
Документа́ция на программное обеспечение — печатные руководства пользователя, диалоговая документация и справочный текст, описывающие, как пользоваться программным продуктом. Документация к современным системам доступна в нескольких форматах: Наиболее старый способ документирования — печатные документы (например, книги, посвященные определенному программному комплексу).
Преимущество печатной документации — в легкости восприятия и (при адекватной организации) в упрощении поиска по неформальным запросам (когда известно, что ищется, но сложно сформулировать конкретные ключевые слова). Электронная документация, которая может быть локальной (например, Readme-файлы) или встраиваться в глобальную систему документации (man, help и так далее).
По сравнению с печатной документацией, электронные документы могут быть более детальными; в них легче проводить поиск по ключевым словам. Документация, размещенная в Интернете.
К этому виду документации относятся не только составленные разработчиками и размещенные на сайте продукта материалы (Getting started, справочные руководства и тому подобное), но и документы, генерируемые пользователями системы. К такой Web 2.0-документации относятся wiki по программным продуктам, записи в блогах, ответы на сайтах вроде stackoverflow и так далее.
Документацию можно писать вручную с использованием систем редактирования и верстки (например, Microsoft Word или LaTeX). Более продуктивный способ — использование генераторов вроде Javadoc и Doxygen.
Как документировать код | 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. Проблемы стандартов единой системы программной документации
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.
Похожие ответы, выполненные работы
- Тест по дисциплине «Математика» для МОИ
- Помощь онлайн по русскому языку на тему…
- Тест по дисциплине «Сайт Романенко Е.В.»…
- Тест по дисциплине «Безопасность…
- Тест по дисциплине «Электронный бизнес» для СибАДИ
- Итоговый тест по дисциплине «Электронный…
- Практическое задание по дисциплине «Основы…
- Практическое задание по дисциплине «Основы…
- Вопросы для самоконтроля по дисциплине…
- Тест по дисциплине «Электронный бизнес» для СибАДИ
Источник: the-distance.ru
Документирование программы
Последней составляющей процесса программирования является документирование. Оно включает широкий спектр описаний, облегчающих процесс программирования и обогащающих результирующую программу. Постоянное документирование должно составлять неотъемлемую часть каждого шага программирования.
Постановка задачи, проектные документы, алгоритмы и программы – все это документы. Внутренняя документация, включенная непосредственно в программу, облегчает чтение кода. Назначение учебного пособия (еще одной формы документации) – научить пользователя применять новую программу; справочное руководство позволяет ознакомиться с описанием команд программного обеспечения.
При разработке программы создается большой объем разнообразной документации. Она необходима как средство передачи информации между разработчиками программы, как средство управления разработкой программы и как средство передачи пользователям информации, необходимой для применения и сопровождения программы.
Пользовательская документация программы
Пользовательская документация программы объясняет пользователям, как они должны действовать, чтобы использовать данную программу. Она необходима, если программа предполагает какое-либо взаимодействие с пользователями. К такой документации относятся документы, которыми руководствуется пользователь при установке программы.
Состав пользовательской документации зависит от аудиторий, на которую ориентировано данное ПО, и от режима использования документов. Аудитория – это пользователи, у которых есть необходимость в определенной пользовательской документации. Хороший пользовательский документ зависит от правильного выбора аудитории, для которой он предназначен.
Качество пользовательской документации существенно определяет успех самой программы. Она должна быть достаточно просто, понятна и удобна для пользователя. Поэтому не редко к созданию конечного варианта документации не редко привлекаются профессиональные технические писатели. Кроме того, для обеспечения более качественной пользовательской документации разработан ряд стандартов, в которых предписывается порядок разработки этой документации.
Понравилась статья? Добавь ее в закладку (CTRL+D) и не забудь поделиться с друзьями:
Источник: studopedia.ru
Как писать техническую документацию для программ на C#
Рано или поздно в жизни каждого разработчика наступает момент, когда он не понимает, как работает его код. Выясняем, что с этим делать.
Евгений Кучерявый
Пишет о программировании, в свободное время создаёт игры. Мечтает открыть свою студию и выпускать ламповые RPG.
Программисты часто сталкиваются с тем, что не могут прочитать код. Такое случается постоянно: когда только приходят в новый проект, когда проверяют код коллеги или — так бывает чаще всего — когда смотрят результат своей же работы. Чтобы этого избежать, нужно писать и читать документацию.
Содержание
- Два вида документации
- Правила хорошего тона в составлении документации
- Где писать документацию в C#
- Как создать файл документации
- Заключение
Разработчики имеют дело с двумя основными видами документации:
- Пользовательская документация. Это руководство по эксплуатации программ. Обычно оно нужно для сложных профессиональных инструментов. Если же пользователи не могут сами разобраться в приложении пиццерии, то лучше доработать интерфейс — добровольно никто инструкцию читать не станет.
- Техническая документация. Это пояснения для программистов, которые будут использовать или дорабатывать существующий код. Они помогут быстро вникнуть в проект и начать работать. Или же продолжить писать программу после долгого перерыва.
К сожалению, не все разработчики (практически никто) любят читать документацию. Любителей писать её и того меньше. Однако делать это очень важно, потому что сложно поддерживать проект без документации.
Правила хорошего тона в составлении документации
Составляя документацию, стоит следовать определенным правилам — они помогают сделать ее более понятной.
1. Документация нужна не всегда
Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.
2. Документация нужна не везде
Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что метод int Sum (int a, int b) возвращает результат сложения двух чисел.
Исключение можно сделать, если речь идет об API или фреймворке, которыми пользуются многие разработчики: они не всегда видят исходный код, но могут использовать классы и методы. Поэтому им важно иметь список доступных методов. В этом случае задокументировать всё нужно просто для галочки.
3. Документация должна быть точной
Очень важно уметь ясно выражать свои мысли. Нужно предельно точно описывать, что делает тот или иной фрагмент кода. Для этого стоит давать как можно более короткие определения. Например:
После этого автоматически будет создано два элемента:
- Summary — общий комментарий. В нем пишут, что делает метод или для чего нужен класс.
- Param — комментарий об аргументе. В нем указывается, какое значение надо передать.
Практически все инструменты, в том числе и Visual Studio, поддерживают вывод подсказок, которые подгружаются из документации. И теперь, если навести на метод Main () или его аргумент, то можно увидеть, что было написано в комментарии.
Такой способ намного лучше, потому что человеку вообще не нужно ничего открывать, чтобы определить, что делает какой-нибудь фрагмент кода. Конечно, наличие XML создает визуальный шум, но его можно просто скрыть.
Еще можно использовать такие XML-элементы, как:
- Returns — возвращаемое значение;
- Value — значение свойства;
- Exception — исключение;
- Remarks — ремарка к основному комментарию.
Таких элементов очень много, подробнее почитать о них можно в документации Microsoft. Цель же этой статьи — показать, как документировать код, чтобы разбираться в проекте стало легче, а не сложнее.
Как создать файл документации
Иногда все-таки нужно сохранить документацию вне кода. Чаще всего ее сохраняют в HTML-формате, а потом загружают на сайт, чтобы разработчики имели к ней доступ.
Для этого сначала нужно зайти в настройки проекта:
А потом перейти во вкладку Build и поставить галочку XML documentation file:
Теперь вместе с компиляцией программы будет создаваться файл с документацией в формате XML. Его можно преобразовать в HTML с помощью специальных утилит. Microsoft для этого рекомендует использовать DocFX или Sandcastle.
Рассмотрим на примере DocFX. Его можно скачать с помощью NuGet Package Manager в Visual Studio. Для этого нажмите на проект правой кнопкой мыши и выберите пункт Manage NuGet Packages:
Затем перейдите во вкладку Browse и введите в поле поиска название docfx.console, а потом нажмите Install:
После нужно подтвердить установку и согласиться с условиями лицензионного соглашения.
Теперь при сборке проекта будет создаваться папка _site, в которой находится сайт с документацией. Однако это касается класса Program, поэтому чтобы проверить работу DocFX, нужно добавить какой-нибудь класс:
Заключение
Многим, и мне в том их числе, гораздо интереснее писать код, а не описывать его. Однако хорошая документация очень важна, если над проектом работает несколько человек или если это API, которым будут пользоваться сторонние программисты.
Кроме того, хорошая практика разработки — когда сначала пишется документация, а потом создаются классы и методы, которые должны ей соответствовать.
- Как работает .NET и зачем он нужен
- Принципы фон Неймана и первые компьютеры на их основе
- Разработка сайтов на 1С-Битрикс для начинающих
Источник: skillbox.ru