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

Содержание

Слайд 1Документирование
Лекция 13

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

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

Слайд 3Классы документов
Эту документацию можно разбить на две группы:
документы управления разработкой

ПС – документация проекта,
документы, входящие в состав ПС – документация продукта

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

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

Слайд 5Типы документов управления
Планы, оценки, расписания. Эти документы создаются менеджерами для прогнозирования

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

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

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

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

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

Слайд 8Типы документов управления
Заметки и переписка. Эти документы фиксируют различные детали взаимодействия

между менеджерами и разработчиками


Слайд 9Документация продукта
Документы, входящие в состав ПС (product documentation), описывают ПС
с точки

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

Слайд 10Типы документов продукта
Эти документы образуют два комплекта с разным назначением:
пользовательская

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


Слайд 11Пользовательская документация
Пользовательская документация ПС (user documentation) объясняет пользователям, как они

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

Слайд 12Категории пользователей
Следует различать две категории пользователей ПС:
ординарных пользователей ПС
и администраторов

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

Слайд 13Категории пользователей
Администратор ПС (system administrator) управляет использованием ПС ординарными пользователями и

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

Слайд 14Состав документации
Состав пользовательской документации зависит от аудиторий пользователей, на которые ориентировано

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Слайд 23Документация сопровождения
Команда разработчиков-сопроводителей должна будет изучать эту документацию и затем вносить

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

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

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

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

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

Слайд 26Документация сопровождения
Кроме того,
для каждого модуля - его спецификация и описание его

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

Слайд 27Документация сопровождения
Документы установления достоверности ПС включают прежде всего документацию по тестированию

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

Слайд 28Документация сопровождения
Документация второй группы содержит Руководство по сопровождению ПС (system maintenance

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

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

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

Слайд 30Автоматизация документирования
Ввиду ограниченности сроков изготовления программных продуктов, они обычно плохо документируются
Решению

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

Слайд 31Генератор документации
Генератор документации — программа или пакет программ, позволяющая получать документацию, предназначенную

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

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

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

Слайд 33Документирующие комментарии
Документирующие комментарии добавляются программистом в процессе написания программного кода и

имеют вид
///
/// Текст комментария
///
Такие комментарии используются при формировании XML-файлов, которые описывают структуру проекта

Слайд 34XML-файлы документации
Файлы документации могут создаваться в процессе построения сборки
Это возможность компилятора

реализуется при установке соответствующей опции:
Проект → Свойства… → Сборка → Вывод → XML-файл документации
Полученный файл документации размещается в папке bin\Debug

Слайд 35Генератор NDoc
Существует большое число генераторов документации, ориентированных на те или иные

языки и среды разработки
Первым из генераторов, ориентированных на платформу .Net Framework, был генератор NDoc, разработанный Кевином Даунсом (Kevin Downs) в начале 2000-х годов

Слайд 36Генератор NDoc
NDoc генерирует документацию библиотек классов на основе .NET сборок и

XML-файлов документации, создаваемых компилятором
NDoc использует подключаемые плагины для создания документации в различных форматах, в том числе:
формате справки MSDN (.CHM),
формате справки Visual Studio (HTML Help 2)
формате веб-страниц MSDN-онлайн

Слайд 37Генератор NDoc
Энтузиазм Кевина Даунса не получил поддержки программистского сообщества и в

конце июля 2006 года он заявил о прекращении своей работы над проектом

Слайд 38Генератор Sandcastle
В том же 2006 году стартует проект Microsoft, преследующий те

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

Слайд 39Отличие от NDoc
В Sandcastle основой всегда является сборка: на основе мета-информации

сборки строится весь справочник, а файл XML-комментариев является необязательным;
В NDoc основным источником являются XML-комментарии, а мета-информация из сборки используется только для тех объектов, которые упоминаются в файле XML-комментариев

Слайд 40Состав Sandcastle
Sandcastle имеет два основных компонента:
MrefBuilder – генерирует XML-файл, используя

механизм отражения (reflection);
BuildAssembler генерирует файлы, выполняет преобразования и т. д.
Действие начинается с работы утилиты MrefBuilder, которая получает информацию из сборки и выдает ее в выходной файл – Reflection.xml

Слайд 41Процесс формирования справочника
Для каждого объекта исходной сборки – пространства имен, класса,

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

Слайд 42Процесс формирования справочника
Следующий шаг состоит в дополнении файла Reflection.xml серией дополнительных

тэгов
Для этого используются XSLT-преобразования, которые выполняются утилитой XslTransform
В результате формируется ряд преобразованных .xml файлов, которые подаются на вход компонента BuildAssembler

Слайд 43Процесс формирования справочника
В частности из Reflection.xml с помощью XSLT-преобразования получают все

файлы, необходимые для сборки справочника .CHM:
.HHC-файл содержания,
.HHK-файл предметного указателя,
.HHP-файл проекта справки

Слайд 44Краткая схема работы Sandcastle
C# or VB
source files
csc /doc
assemblies
XML
files
MrefBuilder
+
xslTransform
Reflection.xml
+
Manifest
BuildAssembler
HTML
topics
project
file
TOC
file
indexes
Help Viewer
HTML Help


Compiler




Sandcastle Libraries

External Tools

Source Files

Слайд 45Подробная схема работы Sandcastle

Слайд 46Sandcastle Help File Builder
Все этапы формирования справочника могут быть выполнены в

режиме командной строки
Кроме того имеется возможность воспользоваться системой Sandcastle Help File Builder, в которой интегрированы средства Sandcastle и удобная инструментальная среда разработки

Слайд 47Установка SHFB
Sandcastle Help File Builder (SHFB) является свободно распространяемой графической оболочкой

над генератором документации Sandcastle
Инсталлятор SHFB доступен по ссылке, приведенной на предыдущем слайде

Слайд 48Окно SHFB

Слайд 49Проект SHFB
Для построения справочника необходимо создать новый проект SHFB
Затем добавить в

него файл сборки и, опционально, xml-файл, полученный при компиляции


Слайд 50Построение проекта
Следующий этап заключается в построении SHFB-проекта Documentation -> Build Project
В

результате получается файл в формате .chm, который может быть просмотрен либо с помощью web-браузера, либо с использованием специальных утилит (например, CHM Decoder)

Слайд 51Конец лекции

Слайд 52Итоговый справочник

Похожие презентации

Рисуем лошадь 218
Работа отряда ЮПП МОУ СОШ № 4 248
День памяти юного героя-антифашиста 280
Технопарк г. Троицка 401
МОУ гимназия № 13 г. Томска 219
День информационных технологий – 15 марта 2007 г. 218

Обратная связь

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

Email: Нажмите что бы посмотреть 

Что такое ThePresentation.ru?

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

Для правообладателей

Яндекс.Метрика