12) Документирование - Технологии программирования

Документирование

Любой проект должен сопровождаться хоть какой-то документацией (прим. редактора = например readme файл с иноформацией о том как именно использовать "таблетку" - это,так сказать , минимальная документация)

Цели документирования

Документация, создаваемая при разработке программных средств необходима для =

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

Классы документов

Эту документацию можно разбить на две группы: =

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

А именно =

ДОКУМЕНТАЦИЯ ПРОЕКТА =

1. Описание проекта
2. Планы
3. Задания исполнителям (задание распределённое между конкретными людьми или группами, участвующими в реализации проекта)
4. отчёт о ходе работ - создаются менеджерами для контролирующих органов
5. Протоколы встреч и обсуждений
6. Отчёты о результатах активности
7. Журналы

ДОКУМЕНТАЦИЯ ПРОДУКТА =

1. Технические требования
2. Технические спецификации
3. Сведения о выпуске (Release notes)
4. Руководства (напр - по эксплуатации и настройки)

-----------------------------------------

ДОКУМЕНТИРОВАНИЕ ПРОЦЕССА РАЗРАБОТКИ (Process documentation)

Документы управления разработкой ПС (process documentation), протоколируют процессы разработки и сопровождения ПС
Они обеспечивают связи внутри коллектива разработчиков и между коллективом разработчиков и менеджерами, управляющими разработкой

--------------------

Типы документов управления

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

Стандарты.

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

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

Рабочие документы.

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

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

Заметки и переписка.

Заметки и переписка - Эти документы фиксируют различные детали взаимодействия между менеджерами ("самой компании-разработчика" - со слов преподавателя) и разработчиками

---------------------------

Product documentation (ДОКУМЕНТАЦИЯ ПРОДУКТА)

Документы, входящие в состав ПС (product documentation), описывают ПС =

1. с точки зрения его применения пользователями,
2. с точки зрения его разработчиков и сопроводителей (в соответствии с назначением ПС)

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

Типы документов продукта

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

1. пользовательская документация ПС (П-документация),
2. документация по сопровождению ПС (С-документация)

Теперь подробнее =

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

Пользовательская документация ПС (user documentation) объясняет пользователям, как они должны действовать, чтобы применить данное ПС
К этому типу документации относятся документы, которыми руководствуется пользователь при:

1. при инсталляции ПС,
2. при применении ПС для решения своих задач,
3. при управлении ПС (например, когда данное ПС взаимодействует с другими системами)

.

Категории пользователей

Следует различать две категории пользователей ПС:

1. ординарных пользователей ПС (те , кто используют ПС для решения своих прикладных задач)
2. и администраторов ПС

Ординарный пользователь ПС (end-user) использует ПС для решения задач в своей предметной области и может не знать многих деталей работы компьютера или принципов программирования

Администратор ПС (system administrator) управляет использованием ПС ординарными пользователями и осуществляет сопровождение ПС, не связанное с модификацией программ

Например, Администратор ПС может =

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

-------------------

Состав документации

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

----------------------

Режим использования документа

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

Обычно пользователю достаточно больших программных систем требуются =

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

Состав пользовательской документации =

1. Общее функциональное описание ПС с краткой характеристикой функциональных возможностей ПС. Предназначено для пользователей, решающих, насколько необходимо им данное ПС = позволяет получить общее представление о программном средстве - и решить нужно ли оно вообще или нет.
2. Руководство по инсталляции ПС, предназначенное для системных администраторов. Оно должно детально описывать действия по установке системы и определять требования к конфигурации аппаратуры.
3. Инструкция по применению ПС. Предназначена для ординарных пользователей и содержит необходимую информацию по применению ПС , организованную в форме удобной для изучения
4. Справочник по применению ПС. Предназначен для ординарных пользователей и содержит необходимую информацию по применению ПС, организованную в форме удобной для избирательного поиска - (например в виде файла windows-спрпавки)
5. Руководство по управлению ПС. Предназначено для системных администраторов и должно описывать сообщения, генерируемые при взаимодействии ПС с другими системами, а также способы реагирования на эти сообщения - Если ПС использует системную аппаратуру, то этот документ может объяснять, как сопровождать эту аппаратуру

-------------

Разработка пользовательской документации

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

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

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

Не всегда получается изложить мысли разработчика в форме понятной для пользователя - но надо стараться или же привлекать так называемых "технических писателей"

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

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

-------------------------------

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

Документация по сопровождению ПС (system documentation) описывает ПС с точки зрения ее разработки

Эта документация необходима, если предполагается изучение устройства ПС и модернизация его программ

То есть тексты пишутся для разработчиков , подобных исполнителям (исполнители - это те, кто изначально создали ПС)

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

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

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

Документация по сопровождению ПС можно разбить на две группы: =

1) Документация, определяющая строение программ и структур данных ПС и технологию их разработки =содержит итоговые документы каждого технологического этапа разработки ПС и включает следующие документы:

1. внешнее описание ПС (Requirements document - то есть описание , с точки зрения зависимости от параметров среды , в которой будут выполняться коды ПС - например - зависимость от операционной системы);
2. описание архитектуры ПС (description of the system architecture), включая внешнюю спецификацию каждой ее программы;
3. для каждой программы ПС - описание ее модульной структуры, включая внешнюю спецификацию каждого включенного в нее модуля;

И ещё =

1. для каждого модуля - его спецификация и описание его строения (design description);
2. тексты модулей на выбранном языке программирования (program source code listings);
3. документы установления достоверности ПС (validation documents), описывающие, как устанавливалась достоверность каждой программы ПС и как информация об установлении достоверности связывалась с требованиями к ПС

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

2) Документацию, помогающую вносить изменения в ПС = содержит Руководство по сопровождению ПС (system maintenance guide), которое описывает:

1. известные проблемы, связанные с ПС,
2. какие части системы являются аппаратно- и программно-зависимыми,
3. возможности дальнейшего развития ПС

Общая проблема сопровождения ПС заключается в обеспечении согласованности всех его представлений при внесении в него любых изменений

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

----------------------------------

Автоматизация документирования

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

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

Генератор документации

Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную для программистов (документация на API) и/или для конечных пользователей системы, по особым образом комментированному исходному коду и, в некоторых случаях, по исполняемым модулям, полученным на выходе компилятора

Принципы работы генератора документации

Генератор анализирует исходный код программы, выделяя синтаксические конструкции, соответствующие значимым объектам программы (типам, классам, процедурам/функциям и т. п.)

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

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